Start removing _EXP defines and improves some docs

Originally we decided to use #define tricks to rename all experimental
symbols so that they had an _EXP suffix so it would be a bit clearer for
those wanting to check for ABI changes that they shouldn't worry about
these experimental symbols.

We feel now though that the defines are a bit more hassle than they are
really worth, since they are one extra thing to remember when coding,
they make using gdb slightly more awkward since you have to use the real
symbol name to set breakpoints and we already have a mechanism for
declaring symbols as experimental via gtk-doc that can be used by anyone
wanting to check for ABI changes.

Instead of just using a script to remove all the #defines we are going
to go through them manually because we need to make sure the symbols
are marked as unstable via gtk-doc. This patch does a first batch of
define removals and in fact some of the symbols didn't have any
documentation at all so that needed to be added too.

Reviewed-by: Neil Roberts <neil@linux.intel.com>

cogl/cogl-bitmap.h

@@ -65,7 +65,6 @@ cogl_bitmap_new_from_file (const char *filename,
 
 #if defined (COGL_ENABLE_EXPERIMENTAL_API)
 
-#define cogl_bitmap_new_from_buffer cogl_bitmap_new_from_buffer_EXP
 /**
  * cogl_bitmap_new_from_buffer:
  * @buffer: A #CoglBuffer containing image data

cogl/cogl-buffer.h

@@ -40,7 +40,7 @@ G_BEGIN_DECLS
 /**
  * SECTION:cogl-buffer
  * @short_description: Common buffer functions, including data upload APIs
- * @stability: Unstable
+ * @stability: unstable
  *
  * The CoglBuffer API provides a common interface to manipulate
  * buffers that have been allocated either via cogl_pixel_buffer_new()
@@ -59,21 +59,6 @@ G_BEGIN_DECLS
  * without blocking other Cogl operations.
  */
 
-/* All of the cogl-buffer API is currently experimental so we suffix
- * the actual symbols with _EXP so if somone is monitoring for ABI
- * changes it will hopefully be clearer to them what's going on if any
- * of the symbols dissapear at a later date.
- */
-#define cogl_is_buffer  cogl_is_buffer_EXP
-#define cogl_buffer_get_size cogl_buffer_get_size_EXP
-#define cogl_buffer_set_usage_hint cogl_buffer_set_usage_hint_EXP
-#define cogl_buffer_get_usage_hint cogl_buffer_get_usage_hint_EXP
-#define cogl_buffer_set_update_hint cogl_buffer_set_update_hint_EXP
-#define cogl_buffer_get_update_hint cogl_buffer_get_update_hint_EXP
-#define cogl_buffer_map cogl_buffer_map_EXP
-#define cogl_buffer_unmap cogl_buffer_unmap_EXP
-#define cogl_buffer_set_data cogl_buffer_set_data_EXP
-
 #define COGL_BUFFER(buffer)     ((CoglBuffer *)(buffer))
 
 typedef struct _CoglBuffer CoglBuffer;
@@ -87,7 +72,7 @@ typedef struct _CoglBuffer CoglBuffer;
  * Return value: %TRUE if the handle is a CoglBuffer, and %FALSE otherwise
  *
  * Since: 1.2
- * Stability: Unstable
+ * Stability: unstable
  */
 gboolean
 cogl_is_buffer (const void *object);
@@ -101,7 +86,7 @@ cogl_is_buffer (const void *object);
  * Return value: the size of the buffer in bytes
  *
  * Since: 1.2
- * Stability: Unstable
+ * Stability: unstable
  */
 unsigned int
 cogl_buffer_get_size (CoglBuffer *buffer);
@@ -117,7 +102,7 @@ cogl_buffer_get_size (CoglBuffer *buffer);
  * the buffer data is going to be updated.
  *
  * Since: 1.2
- * Stability: Unstable
+ * Stability: unstable
  */
 typedef enum { /*< prefix=COGL_BUFFER_UPDATE_HINT >*/
   COGL_BUFFER_UPDATE_HINT_STATIC,
@@ -134,7 +119,7 @@ typedef enum { /*< prefix=COGL_BUFFER_UPDATE_HINT >*/
  * of the available hints.
  *
  * Since: 1.2
- * Stability: Unstable
+ * Stability: unstable
  */
 void
 cogl_buffer_set_update_hint (CoglBuffer          *buffer,
@@ -149,7 +134,7 @@ cogl_buffer_set_update_hint (CoglBuffer          *buffer,
  * Return value: the #CoglBufferUpdateHint currently used by the buffer
  *
  * Since: 1.2
- * Stability: Unstable
+ * Stability: unstable
  */
 CoglBufferUpdateHint
 cogl_buffer_get_update_hint (CoglBuffer *buffer);
@@ -164,7 +149,7 @@ cogl_buffer_get_update_hint (CoglBuffer *buffer);
  * The access hints for cogl_buffer_set_update_hint()
  *
  * Since: 1.2
- * Stability: Unstable
+ * Stability: unstable
  */
 typedef enum { /*< prefix=COGL_BUFFER_ACCESS >*/
  COGL_BUFFER_ACCESS_READ       = 1 << 0,
@@ -182,7 +167,7 @@ typedef enum { /*< prefix=COGL_BUFFER_ACCESS >*/
  * is mapped.
  *
  * Since: 1.4
- * Stability: Unstable
+ * Stability: unstable
  */
 typedef enum { /*< prefix=COGL_BUFFER_MAP_HINT >*/
   COGL_BUFFER_MAP_HINT_DISCARD = 1 << 0
@@ -211,7 +196,7 @@ typedef enum { /*< prefix=COGL_BUFFER_MAP_HINT >*/
  * Return value: A pointer to the mapped memory or %NULL is the call fails
  *
  * Since: 1.2
- * Stability: Unstable
+ * Stability: unstable
  */
 void *
 cogl_buffer_map (CoglBuffer        *buffer,
@@ -225,7 +210,7 @@ cogl_buffer_map (CoglBuffer        *buffer,
  * Unmaps a buffer previously mapped by cogl_buffer_map().
  *
  * Since: 1.2
- * Stability: Unstable
+ * Stability: unstable
  */
 void
 cogl_buffer_unmap (CoglBuffer *buffer);
@@ -244,7 +229,7 @@ cogl_buffer_unmap (CoglBuffer *buffer);
  * Return value: %TRUE is the operation succeeded, %FALSE otherwise
  *
  * Since: 1.2
- * Stability: Unstable
+ * Stability: unstable
  */
 gboolean
 cogl_buffer_set_data (CoglBuffer  *buffer,

cogl/cogl-context.h

@@ -43,36 +43,94 @@ G_BEGIN_DECLS
  * SECTION:cogl-context
  * @short_description: The top level application context.
  *
- * A CoglContext is the topmost sandbox of Cogl state for an
+ * A #CoglContext is the top most sandbox of Cogl state for an
- * application or toolkit. Its main purpose is to bind together the
+ * application or toolkit. Its main purpose is to act as a sandbox
- * key state objects at any one time; with the most significant being
+ * for the memory management of state objects. Normally an application
- * the current framebuffer being drawn too (See #CoglFramebuffer for
+ * will only create a single context since there is no way to share
- * more details) and the current GPU pipeline configuration (See
+ * resources between contexts.
- * #CoglPipeline for more details).
+ *
+ * For those familiar with OpenGL or perhaps Cairo it should be
+ * understood that unlike these APIs a Cogl context isn't a rendering
+ * context as such. In other words Cogl doesn't aim to provide a state
+ * machine style model for configuring rendering parameters. Most
+ * rendering state in Cogl is directly associated with user managed
+ * objects called pipelines and geometry is drawn with a specific
+ * pipeline object to a framebuffer object and those 3 things fully
+ * define the state for drawing. This is an important part of Cogl's
+ * design since it helps you write orthogonal rendering components
+ * that can all access the same GPU without having to worry about
+ * what state other components have left you with.
  */
 
 typedef struct _CoglContext	      CoglContext;
 
 #define COGL_CONTEXT(OBJECT) ((CoglContext *)OBJECT)
 
-#define cogl_context_new cogl_context_new_EXP
+/**
-
+ * cogl_context_new:
+ * @display: A #CoglDisplay pointer
+ * @error: A GError return location.
+ *
+ * Creates a new #CoglContext which acts as an application sandbox
+ * for any state objects that are allocated.
+ *
+ * Return value: (transfer full): A newly allocated #CoglContext
+ * Since: 1.8
+ * Stability: unstable
+ */
 CoglContext *
 cogl_context_new (CoglDisplay *display,
                   GError **error);
 
-#define cogl_context_get_display cogl_context_get_display_EXP
+/**
+ * cogl_context_get_display:
+ * @context: A #CoglContext pointer
+ *
+ * Retrieves the #CoglDisplay that is internally associated with the
+ * given @context. This will return the same #CoglDisplay that was
+ * passed to cogl_context_new() or if %NULL was passed to
+ * cogl_context_new() then this function returns a pointer to the
+ * display that was automatically setup internally.
+ *
+ * Return value: (transfer none): The #CoglDisplay associated with the
+ *               given @context.
+ * Since: 1.8
+ * Stability: unstable
+ */
 CoglDisplay *
 cogl_context_get_display (CoglContext *context);
 
 #ifdef COGL_HAS_EGL_SUPPORT
-#define cogl_egl_context_get_egl_display cogl_egl_context_get_egl_display_EXP
+/**
+ * cogl_egl_context_get_egl_display:
+ * @context: A #CoglContext pointer
+ *
+ * If you have done a runtime check to determine that Cogl is using
+ * EGL internally then this API can be used to retrieve the EGLDisplay
+ * handle that was setup internally. The result is undefined if Cogl
+ * is not using EGL.
+ *
+ * Return value: The internally setup EGLDisplay handle.
+ * Since: 1.8
+ * Stability: unstable
+ */
 EGLDisplay
 cogl_egl_context_get_egl_display (CoglContext *context);
 #endif
 
 #ifdef COGL_HAS_EGL_PLATFORM_ANDROID_SUPPORT
-#define cogl_android_set_native_window cogl_android_set_native_window_EXP
+/**
+ * cogl_android_set_native_window:
+ * @window: A native Android window
+ *
+ * Allows Android applications to inform Cogl of the native window
+ * that they have been given which Cogl can render too. On Android
+ * this API must be used before creating a #CoglRenderer, #CoglDisplay
+ * and #CoglContext.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
 void
 cogl_android_set_native_window (ANativeWindow *window);
 #endif

cogl/cogl-texture-2d-sliced.h

@@ -66,8 +66,6 @@
 typedef struct _CoglTexture2DSliced CoglTexture2DSliced;
 #define COGL_TEXTURE_2D_SLICED(X) ((CoglTexture2DSliced *)X)
 
-#define cogl_texture_2d_sliced_new_with_size \
-  cogl_texture_2d_sliced_new_with_size_EXP
 /**
  * cogl_texture_2d_sliced_new_with_size:
  * @ctx: A #CoglContext