From c4767b6c0126c6313df5e8fe91baf501916cc25a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Corentin=20No=C3=ABl?= <tintou@noel.tf>
Date: Tue, 27 Feb 2024 08:48:30 +0100
Subject: [PATCH] cogl: Increase annotation coverage

Upstream the annotations used in Gala, make more Cogl methods available since
things got moved to a GObject base and thus works natively with the introspection.

Add all the public API to the introspection.

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/3619>
---
 cogl/cogl/cogl-atlas-texture.h        |  4 +--
 cogl/cogl/cogl-attribute-buffer.h     |  4 +--
 cogl/cogl/cogl-bitmap.h               | 11 +++---
 cogl/cogl/cogl-buffer.h               |  3 +-
 cogl/cogl/cogl-context.h              | 11 ++++--
 cogl/cogl/cogl-dma-buf-handle.h       | 17 +++++-----
 cogl/cogl/cogl-fence.h                | 10 +++---
 cogl/cogl/cogl-frame-info.h           |  3 --
 cogl/cogl/cogl-framebuffer.h          |  2 +-
 cogl/cogl/cogl-indices.h              | 10 ++++++
 cogl/cogl/cogl-meta-texture.h         |  6 ++--
 cogl/cogl/cogl-offscreen.h            |  4 ++-
 cogl/cogl/cogl-onscreen.h             |  6 ++--
 cogl/cogl/cogl-pipeline-layer-state.h |  6 ++--
 cogl/cogl/cogl-pipeline-state.h       |  6 ++--
 cogl/cogl/cogl-pixel-buffer.h         |  3 +-
 cogl/cogl/cogl-primitive.h            | 48 +++++++++++++--------------
 cogl/cogl/cogl-renderer.h             |  6 ++--
 cogl/cogl/cogl-scanout.h              |  5 +++
 cogl/cogl/cogl-texture-2d-sliced.h    |  6 ++--
 cogl/cogl/cogl-texture-2d.h           |  8 ++---
 cogl/cogl/cogl-texture.h              |  2 +-
 cogl/cogl/cogl-types.h                |  2 +-
 cogl/cogl/meson.build                 | 42 +++++++++++------------
 24 files changed, 126 insertions(+), 99 deletions(-)

diff --git a/cogl/cogl/cogl-atlas-texture.h b/cogl/cogl/cogl-atlas-texture.h
index 3008e295b..086db3c0f 100644
--- a/cogl/cogl/cogl-atlas-texture.h
+++ b/cogl/cogl/cogl-atlas-texture.h
@@ -164,10 +164,10 @@ cogl_atlas_texture_new_from_data (CoglContext *ctx,
 
 /**
  * cogl_atlas_texture_new_from_bitmap:
- * @bitmap: A #CoglBitmap
+ * @bmp: A #CoglBitmap
  *
  * Creates a new #CoglAtlasTexture texture based on data residing in a
- * @bitmap. A #CoglAtlasTexture represents a sub-region within one of
+ * @bmp. A #CoglAtlasTexture represents a sub-region within one of
  * Cogl's shared texture atlases.
  *
  * The storage for the texture is not allocated before this function
diff --git a/cogl/cogl/cogl-attribute-buffer.h b/cogl/cogl/cogl-attribute-buffer.h
index fa083a043..45040f7d9 100644
--- a/cogl/cogl/cogl-attribute-buffer.h
+++ b/cogl/cogl/cogl-attribute-buffer.h
@@ -98,8 +98,8 @@ cogl_attribute_buffer_new_with_size (CoglContext *context,
  * cogl_attribute_buffer_new:
  * @context: A #CoglContext
  * @bytes: The number of bytes to allocate for vertex attribute data.
- * @data: (array length=bytes): An optional pointer to vertex data to
- *        upload immediately.
+ * @data: (array length=bytes) (element-type guint8): An optional
+ *        pointer to vertex data to upload immediately.
  *
  * Describes a new #CoglAttributeBuffer of @size bytes to contain
  * arrays of vertex attribute data and also uploads @size bytes read
diff --git a/cogl/cogl/cogl-bitmap.h b/cogl/cogl/cogl-bitmap.h
index de894361a..c9a35f69f 100644
--- a/cogl/cogl/cogl-bitmap.h
+++ b/cogl/cogl/cogl-bitmap.h
@@ -67,7 +67,7 @@ G_DECLARE_FINAL_TYPE (CoglBitmap,
                       GObject)
 
 /**
- * cogl_bitmap_new_from_buffer: (skip)
+ * cogl_bitmap_new_from_buffer:
  * @buffer: A #CoglBuffer containing image data
  * @format: The #CoglPixelFormat defining the format of the image data
  *          in the given @buffer.
@@ -91,7 +91,7 @@ cogl_bitmap_new_from_buffer (CoglBuffer *buffer,
                              int offset);
 
 /**
- * cogl_bitmap_new_with_size: (skip)
+ * cogl_bitmap_new_with_size:
  * @context: A #CoglContext
  * @width: width of the bitmap in pixels
  * @height: height of the bitmap in pixels
@@ -123,14 +123,15 @@ cogl_bitmap_new_with_size (CoglContext *context,
                            CoglPixelFormat format);
 
 /**
- * cogl_bitmap_new_for_data: (skip)
+ * cogl_bitmap_new_for_data:
  * @context: A #CoglContext
  * @width: The width of the bitmap.
  * @height: The height of the bitmap.
  * @format: The format of the pixel data.
  * @rowstride: The rowstride of the bitmap (the number of bytes from
  *   the start of one row of the bitmap to the next).
- * @data: A pointer to the data. The bitmap will take ownership of this data.
+ * @data: (array) (transfer full): A pointer to the data. The bitmap will take
+ *   ownership of this data.
  *
  * Creates a bitmap using some existing data. The data is not copied
  * so the application must keep the buffer alive for the lifetime of
@@ -187,7 +188,7 @@ COGL_EXPORT int
 cogl_bitmap_get_rowstride (CoglBitmap *bitmap);
 
 /**
- * cogl_bitmap_get_buffer: (skip)
+ * cogl_bitmap_get_buffer:
  * @bitmap: A #CoglBitmap
  *
  * Return value: (transfer none): the #CoglPixelBuffer that this
diff --git a/cogl/cogl/cogl-buffer.h b/cogl/cogl/cogl-buffer.h
index e1da58704..c73cfad06 100644
--- a/cogl/cogl/cogl-buffer.h
+++ b/cogl/cogl/cogl-buffer.h
@@ -278,7 +278,8 @@ cogl_buffer_unmap (CoglBuffer *buffer);
  * cogl_buffer_set_data:
  * @buffer: a buffer object
  * @offset: destination offset (in bytes) in the buffer
- * @data: a pointer to the data to be copied into the buffer
+ * @data: (array) (element-type guint8): a pointer to the data to be copied
+ *   into the buffer
  * @size: number of bytes to copy
  *
  * Updates part of the buffer with new data from @data. Where to put this new
diff --git a/cogl/cogl/cogl-context.h b/cogl/cogl/cogl-context.h
index 34d47cb03..614a351fe 100644
--- a/cogl/cogl/cogl-context.h
+++ b/cogl/cogl/cogl-context.h
@@ -103,7 +103,7 @@ G_DECLARE_FINAL_TYPE (CoglContext,
                       GObject)
 
 /**
- * cogl_context_new: (constructor) (skip)
+ * cogl_context_new: (constructor)
  * @display: (allow-none): A #CoglDisplay pointer
  * @error: A GError return location.
  *
@@ -117,7 +117,7 @@ cogl_context_new (CoglDisplay *display,
                   GError **error);
 
 /**
- * cogl_context_get_display: (skip)
+ * cogl_context_get_display:
  * @context: A #CoglContext pointer
  *
  * Retrieves the #CoglDisplay that is internally associated with the
@@ -133,7 +133,7 @@ COGL_EXPORT CoglDisplay *
 cogl_context_get_display (CoglContext *context);
 
 /**
- * cogl_context_get_renderer: (skip)
+ * cogl_context_get_renderer:
  * @context: A #CoglContext pointer
  *
  * Retrieves the #CoglRenderer that is internally associated with the
@@ -342,6 +342,11 @@ COGL_EXPORT CoglPipeline *
 cogl_context_get_named_pipeline (CoglContext     *context,
                                  CoglPipelineKey *key);
 
+/**
+ * cogl_context_free_timestamp_query:
+ * @context: a #CoglContext pointer
+ * @query: (transfer full): a #CoglTimestampQuery
+ */
 COGL_EXPORT void
 cogl_context_free_timestamp_query (CoglContext        *context,
                                    CoglTimestampQuery *query);
diff --git a/cogl/cogl/cogl-dma-buf-handle.h b/cogl/cogl/cogl-dma-buf-handle.h
index f963add30..ba469ceeb 100644
--- a/cogl/cogl/cogl-dma-buf-handle.h
+++ b/cogl/cogl/cogl-dma-buf-handle.h
@@ -53,7 +53,8 @@ cogl_dma_buf_handle_new (CoglFramebuffer *framebuffer,
                          GDestroyNotify   destroy_func);
 
 /**
- * cogl_dma_buf_handle_free: (skip)
+ * cogl_dma_buf_handle_free:
+ * @dmabuf_handle: (transfer full): a #CoglDmaBufHandle
  *
  * Releases @dmabuf_handle; it is a programming error to release
  * an already released handle.
@@ -79,7 +80,7 @@ cogl_dma_buf_handle_munmap (CoglDmaBufHandle  *dmabuf_handle,
                             GError           **error);
 
 /**
- * cogl_dma_buf_handle_get_framebuffer: (skip)
+ * cogl_dma_buf_handle_get_framebuffer:
  *
  * Retrieves the #CoglFramebuffer, backed by an exported DMABuf buffer,
  * of @dmabuf_handle.
@@ -90,7 +91,7 @@ COGL_EXPORT CoglFramebuffer *
 cogl_dma_buf_handle_get_framebuffer (CoglDmaBufHandle *dmabuf_handle);
 
 /**
- * cogl_dma_buf_handle_get_fd: (skip)
+ * cogl_dma_buf_handle_get_fd:
  *
  * Retrieves the file descriptor of @dmabuf_handle.
  *
@@ -100,7 +101,7 @@ COGL_EXPORT int
 cogl_dma_buf_handle_get_fd (CoglDmaBufHandle *dmabuf_handle);
 
 /**
- * cogl_dmabuf_handle_get_width: (skip)
+ * cogl_dmabuf_handle_get_width:
  *
  * Returns: the buffer width
  */
@@ -108,7 +109,7 @@ COGL_EXPORT int
 cogl_dma_buf_handle_get_width (CoglDmaBufHandle *dmabuf_handle);
 
 /**
- * cogl_dmabuf_handle_get_height: (skip)
+ * cogl_dmabuf_handle_get_height:
  *
  * Returns: the buffer height
  */
@@ -116,7 +117,7 @@ COGL_EXPORT int
 cogl_dma_buf_handle_get_height (CoglDmaBufHandle *dmabuf_handle);
 
 /**
- * cogl_dmabuf_handle_get_stride: (skip)
+ * cogl_dmabuf_handle_get_stride:
  *
  * Returns: the buffer stride
  */
@@ -124,7 +125,7 @@ COGL_EXPORT int
 cogl_dma_buf_handle_get_stride (CoglDmaBufHandle *dmabuf_handle);
 
 /**
- * cogl_dmabuf_handle_get_offset: (skip)
+ * cogl_dmabuf_handle_get_offset:
  *
  * Returns: the buffer offset
  */
@@ -132,7 +133,7 @@ COGL_EXPORT int
 cogl_dma_buf_handle_get_offset (CoglDmaBufHandle *dmabuf_handle);
 
 /**
- * cogl_dmabuf_handle_get_bpp: (skip)
+ * cogl_dmabuf_handle_get_bpp:
  *
  * Returns: the number of bytes per pixel
  */
diff --git a/cogl/cogl/cogl-fence.h b/cogl/cogl/cogl-fence.h
index 3e70c3bf8..e97b73b66 100644
--- a/cogl/cogl/cogl-fence.h
+++ b/cogl/cogl/cogl-fence.h
@@ -83,17 +83,17 @@ cogl_fence_closure_get_user_data (CoglFenceClosure *closure);
 /**
  * cogl_framebuffer_add_fence_callback:
  * @framebuffer: The #CoglFramebuffer the commands have been submitted to
- * @callback: (scope notified): A #CoglFenceCallback to be called when
+ * @callback: (scope async): A #CoglFenceCallback to be called when
  *            all commands submitted to Cogl have been executed
  * @user_data: (closure): Private data that will be passed to the callback
  *
  * Calls the provided callback when all previously-submitted commands have
  * been executed by the GPU.
  *
- * Returns non-NULL if the fence succeeded, or %NULL if it was unable to
- * be inserted and the callback will never be called.  The user does not
- * need to free the closure; it will be freed automatically when the
- * callback is called, or cancelled.
+ * Returns: (transfer none) (nullable): non-NULL if the fence succeeded,
+ * or %NULL if it was unable to  be inserted and the callback will never be
+ * called.  The user does not need to free the closure; it will be freed
+ * automatically when the callback is called, or cancelled.
  */
 COGL_EXPORT CoglFenceClosure *
 cogl_framebuffer_add_fence_callback (CoglFramebuffer *framebuffer,
diff --git a/cogl/cogl/cogl-frame-info.h b/cogl/cogl/cogl-frame-info.h
index 2ead975aa..e14e2e5ac 100644
--- a/cogl/cogl/cogl-frame-info.h
+++ b/cogl/cogl/cogl-frame-info.h
@@ -109,9 +109,6 @@ int64_t cogl_frame_info_get_presentation_time_us (CoglFrameInfo *info);
 COGL_EXPORT
 float cogl_frame_info_get_refresh_rate (CoglFrameInfo *info);
 
-/**
- * cogl_frame_info_get_global_frame_counter: (skip)
- */
 COGL_EXPORT
 int64_t cogl_frame_info_get_global_frame_counter (CoglFrameInfo *info);
 
diff --git a/cogl/cogl/cogl-framebuffer.h b/cogl/cogl/cogl-framebuffer.h
index 92b495afa..9f25e4be6 100644
--- a/cogl/cogl/cogl-framebuffer.h
+++ b/cogl/cogl/cogl-framebuffer.h
@@ -495,7 +495,7 @@ cogl_framebuffer_push_rectangle_clip (CoglFramebuffer *framebuffer,
                                       float y_2);
 
 /**
- * cogl_framebuffer_push_primitive_clip: (skip)
+ * cogl_framebuffer_push_primitive_clip:
  * @framebuffer: A #CoglFramebuffer pointer
  * @primitive: A #CoglPrimitive describing a flat 2D shape
  * @bounds_x1: x coordinate for the top-left corner of the primitives
diff --git a/cogl/cogl/cogl-indices.h b/cogl/cogl/cogl-indices.h
index be91fbba6..57124168d 100644
--- a/cogl/cogl/cogl-indices.h
+++ b/cogl/cogl/cogl-indices.h
@@ -124,6 +124,11 @@ cogl_indices_new_for_buffer (CoglIndicesType type,
                              CoglIndexBuffer *buffer,
                              size_t offset);
 
+/**
+ * cogl_indices_get_buffer:
+ *
+ * Returns: (transfer none): a #CoglIndexBuffer
+ */
 COGL_EXPORT CoglIndexBuffer *
 cogl_indices_get_buffer (CoglIndices *indices);
 
@@ -137,6 +142,11 @@ COGL_EXPORT void
 cogl_indices_set_offset (CoglIndices *indices,
                          size_t offset);
 
+/**
+ * cogl_get_rectangle_indices:
+ *
+ * Returns: (transfer none): a #CoglIndices
+ */
 COGL_EXPORT CoglIndices *
 cogl_get_rectangle_indices (CoglContext *context, int n_rectangles);
 
diff --git a/cogl/cogl/cogl-meta-texture.h b/cogl/cogl/cogl-meta-texture.h
index 8257df7e2..59a335b8e 100644
--- a/cogl/cogl/cogl-meta-texture.h
+++ b/cogl/cogl/cogl-meta-texture.h
@@ -39,6 +39,7 @@
 G_BEGIN_DECLS
 
 /**
+ * SECTION:meta-texture
  * Interface for high-level textures built from 
  * low-level textures like #CoglTexture2D.
  *
@@ -119,15 +120,14 @@ typedef void (*CoglMetaTextureCallback) (CoglTexture *sub_texture,
 
 /**
  * cogl_meta_texture_foreach_in_region:
- * @meta_texture: An object implementing the #CoglMetaTexture
- *                interface.
+ * @texture: An object implementing the #CoglMetaTexture interface.
  * @tx_1: The top-left x coordinate of the region to iterate
  * @ty_1: The top-left y coordinate of the region to iterate
  * @tx_2: The bottom-right x coordinate of the region to iterate
  * @ty_2: The bottom-right y coordinate of the region to iterate
  * @wrap_s: The wrap mode for the x-axis
  * @wrap_t: The wrap mode for the y-axis
- * @callback: A #CoglMetaTextureCallback pointer to be called
+ * @callback: (scope call): A #CoglMetaTextureCallback pointer to be called
  *            for each low-level texture within the specified region.
  * @user_data: A private pointer that is passed to @callback.
  *
diff --git a/cogl/cogl/cogl-offscreen.h b/cogl/cogl/cogl-offscreen.h
index b97807ab3..79f8877e1 100644
--- a/cogl/cogl/cogl-offscreen.h
+++ b/cogl/cogl/cogl-offscreen.h
@@ -91,7 +91,9 @@ COGL_EXPORT CoglOffscreen *
 cogl_offscreen_new_with_texture (CoglTexture *texture);
 
 /**
- * cogl_offscreen_get_texture: (skip)
+ * cogl_offscreen_get_texture:
+ *
+ * Returns: (transfer none): a #CoglTexture
  */
 COGL_EXPORT CoglTexture *
 cogl_offscreen_get_texture (CoglOffscreen *offscreen);
diff --git a/cogl/cogl/cogl-onscreen.h b/cogl/cogl/cogl-onscreen.h
index 33928d31e..8419376e1 100644
--- a/cogl/cogl/cogl-onscreen.h
+++ b/cogl/cogl/cogl-onscreen.h
@@ -279,7 +279,7 @@ cogl_onscreen_swap_buffers_with_damage (CoglOnscreen *onscreen,
                                         gpointer user_data);
 
 /**
- * cogl_onscreen_direct_scanout: (skip)
+ * cogl_onscreen_direct_scanout:
  */
 COGL_EXPORT gboolean
 cogl_onscreen_direct_scanout (CoglOnscreen   *onscreen,
@@ -289,7 +289,9 @@ cogl_onscreen_direct_scanout (CoglOnscreen   *onscreen,
                               GError        **error);
 
 /**
- * cogl_onscreen_add_frame_info: (skip)
+ * cogl_onscreen_add_frame_info:
+ * @onscreen: A #CoglOnscreen framebuffer
+ * @info: (transfer full): A #CoglFrameInfo
  */
 COGL_EXPORT void
 cogl_onscreen_add_frame_info (CoglOnscreen  *onscreen,
diff --git a/cogl/cogl/cogl-pipeline-layer-state.h b/cogl/cogl/cogl-pipeline-layer-state.h
index 71d7a6928..c3ea36d05 100644
--- a/cogl/cogl/cogl-pipeline-layer-state.h
+++ b/cogl/cogl/cogl-pipeline-layer-state.h
@@ -306,8 +306,10 @@ cogl_pipeline_get_n_layers (CoglPipeline *pipeline);
  * cogl_pipeline_get_layer_filters:
  * @pipeline: A #CoglPipeline object
  * @layer_index: the layer number to change.
- * @min_filter: Return location for the filter used when scaling a texture down.
- * @mag_filter: Return location for the filter used when magnifying a texture.
+ * @min_filter: (out): Return location for the filter used when scaling
+ *   a texture down.
+ * @mag_filter: (out): Return location for the filter used when magnifying
+ *   a texture.
  *
  * Returns the decimation and interpolation filters used when a texture is
  * drawn at other scales than 100%.
diff --git a/cogl/cogl/cogl-pipeline-state.h b/cogl/cogl/cogl-pipeline-state.h
index 7effdc460..0650687f8 100644
--- a/cogl/cogl/cogl-pipeline-state.h
+++ b/cogl/cogl/cogl-pipeline-state.h
@@ -348,7 +348,7 @@ cogl_pipeline_set_user_program (CoglPipeline *pipeline,
                                 CoglProgram  *program);
 
 /**
- * cogl_pipeline_set_depth_state: (skip)
+ * cogl_pipeline_set_depth_state:
  * @pipeline: A #CoglPipeline object
  * @state: A #CoglDepthState struct
  * @error: A #GError to report failures to setup the given @state.
@@ -361,7 +361,7 @@ cogl_pipeline_set_user_program (CoglPipeline *pipeline,
  * Note: Since some platforms do not support the depth range feature
  * it is possible for this function to fail and report an @error.
  *
- * Returns: TRUE if the GPU supports all the given @state else %FALSE
+ * Returns: %TRUE if the GPU supports all the given @state else %FALSE
  *          and returns an @error.
  */
 COGL_EXPORT gboolean
@@ -370,7 +370,7 @@ cogl_pipeline_set_depth_state (CoglPipeline *pipeline,
                                GError **error);
 
 /**
- * cogl_pipeline_get_depth_state: (skip)
+ * cogl_pipeline_get_depth_state:
  * @pipeline: A #CoglPipeline object
  * @state_out: (out): A destination #CoglDepthState struct
  *
diff --git a/cogl/cogl/cogl-pixel-buffer.h b/cogl/cogl/cogl-pixel-buffer.h
index 3acb1d79b..e7abe0888 100644
--- a/cogl/cogl/cogl-pixel-buffer.h
+++ b/cogl/cogl/cogl-pixel-buffer.h
@@ -72,7 +72,8 @@ GType               cogl_pixel_buffer_get_type       (void) G_GNUC_CONST;
  * cogl_pixel_buffer_new:
  * @context: A #CoglContext
  * @size: The number of bytes to allocate for the pixel data.
- * @data: An optional pointer to vertex data to upload immediately
+ * @data: (array length=size) (element-type guint8): An optional pointer to
+ *   vertex data to upload immediately
  *
  * Declares a new #CoglPixelBuffer of @size bytes to contain arrays of
  * pixels. Once declared, data can be set using cogl_buffer_set_data()
diff --git a/cogl/cogl/cogl-primitive.h b/cogl/cogl/cogl-primitive.h
index e98cc7d3c..0de14b289 100644
--- a/cogl/cogl/cogl-primitive.h
+++ b/cogl/cogl/cogl-primitive.h
@@ -220,10 +220,10 @@ cogl_primitive_new (CoglVerticesMode mode,
                     ...);
 
 /**
- * cogl_primitive_new_with_attributes: (skip)
+ * cogl_primitive_new_with_attributes:
  * @mode: A #CoglVerticesMode defining how to draw the vertices
  * @n_vertices: The number of vertices to process when drawing
- * @attributes: An array of CoglAttribute
+ * @attributes: (array length=n_attributes): An array of CoglAttribute
  * @n_attributes: The number of attributes
  *
  * Combines a set of `CoglAttribute`s with a specific draw @mode
@@ -244,12 +244,12 @@ cogl_primitive_new_with_attributes (CoglVerticesMode mode,
                                     int n_attributes);
 
 /**
- * cogl_primitive_new_p2: (skip)
+ * cogl_primitive_new_p2:
  * @context: A #CoglContext
  * @mode: A #CoglVerticesMode defining how to draw the vertices
  * @n_vertices: The number of vertices to read from @data and also
  *              the number of vertices to read when later drawing.
- * @data: (array length=n_vertices): (type Cogl.VertexP2): An array
+ * @data: (array length=n_vertices) (element-type Cogl.VertexP2): An array
  *        of #CoglVertexP2 vertices
  *
  * Provides a convenient way to describe a primitive, such as a single
@@ -294,12 +294,12 @@ cogl_primitive_new_p2 (CoglContext *context,
                        const CoglVertexP2 *data);
 
 /**
- * cogl_primitive_new_p3: (skip)
+ * cogl_primitive_new_p3:
  * @context: A #CoglContext
  * @mode: A #CoglVerticesMode defining how to draw the vertices
  * @n_vertices: The number of vertices to read from @data and also
  *              the number of vertices to read when later drawing.
- * @data: (array length=n_vertices): (type Cogl.VertexP3): An array of
+ * @data: (array length=n_vertices) (element-type Cogl.VertexP3): An array of
  *        #CoglVertexP3 vertices
  *
  * Provides a convenient way to describe a primitive, such as a single
@@ -344,12 +344,12 @@ cogl_primitive_new_p3 (CoglContext *context,
                        const CoglVertexP3 *data);
 
 /**
- * cogl_primitive_new_p2c4: (skip)
+ * cogl_primitive_new_p2c4:
  * @context: A #CoglContext
  * @mode: A #CoglVerticesMode defining how to draw the vertices
  * @n_vertices: The number of vertices to read from @data and also
  *              the number of vertices to read when later drawing.
- * @data: (array length=n_vertices): (type Cogl.VertexP2C4): An array
+ * @data: (array length=n_vertices) (element-type Cogl.VertexP2C4): An array
  *        of #CoglVertexP2C4 vertices
  *
  * Provides a convenient way to describe a primitive, such as a single
@@ -396,12 +396,12 @@ cogl_primitive_new_p2c4 (CoglContext *context,
                          const CoglVertexP2C4 *data);
 
 /**
- * cogl_primitive_new_p3c4: (skip)
+ * cogl_primitive_new_p3c4:
  * @context: A #CoglContext
  * @mode: A #CoglVerticesMode defining how to draw the vertices
  * @n_vertices: The number of vertices to read from @data and also
  *              the number of vertices to read when later drawing.
- * @data: (array length=n_vertices): (type Cogl.VertexP3C4): An array
+ * @data: (array length=n_vertices) (element-type Cogl.VertexP3C4): An array
  *        of #CoglVertexP3C4 vertices
  *
  * Provides a convenient way to describe a primitive, such as a single
@@ -448,12 +448,12 @@ cogl_primitive_new_p3c4 (CoglContext *context,
                          const CoglVertexP3C4 *data);
 
 /**
- * cogl_primitive_new_p2t2: (skip)
+ * cogl_primitive_new_p2t2:
  * @context: A #CoglContext
  * @mode: A #CoglVerticesMode defining how to draw the vertices
  * @n_vertices: The number of vertices to read from @data and also
  *              the number of vertices to read when later drawing.
- * @data: (array length=n_vertices): (type Cogl.VertexP2T2): An array
+ * @data: (array length=n_vertices) (element-type Cogl.VertexP2T2): An array
  *        of #CoglVertexP2T2 vertices
  *
  * Provides a convenient way to describe a primitive, such as a single
@@ -500,12 +500,12 @@ cogl_primitive_new_p2t2 (CoglContext *context,
                          const CoglVertexP2T2 *data);
 
 /**
- * cogl_primitive_new_p3t2: (skip)
+ * cogl_primitive_new_p3t2:
  * @context: A #CoglContext
  * @mode: A #CoglVerticesMode defining how to draw the vertices
  * @n_vertices: The number of vertices to read from @data and also
  *              the number of vertices to read when later drawing.
- * @data: (array length=n_vertices): (type Cogl.VertexP3T2): An array
+ * @data: (array length=n_vertices) (element-type Cogl.VertexP3T2): An array
  *        of #CoglVertexP3T2 vertices
  *
  * Provides a convenient way to describe a primitive, such as a single
@@ -552,12 +552,12 @@ cogl_primitive_new_p3t2 (CoglContext *context,
                          const CoglVertexP3T2 *data);
 
 /**
- * cogl_primitive_new_p2t2c4: (skip)
+ * cogl_primitive_new_p2t2c4:
  * @context: A #CoglContext
  * @mode: A #CoglVerticesMode defining how to draw the vertices
  * @n_vertices: The number of vertices to read from @data and also
  *              the number of vertices to read when later drawing.
- * @data: (array length=n_vertices): (type Cogl.VertexP2T2C4): An
+ * @data: (array length=n_vertices) (element-type Cogl.VertexP2T2C4): An
  *        array of #CoglVertexP2T2C4 vertices
  *
  * Provides a convenient way to describe a primitive, such as a single
@@ -604,12 +604,12 @@ cogl_primitive_new_p2t2c4 (CoglContext *context,
                            const CoglVertexP2T2C4 *data);
 
 /**
- * cogl_primitive_new_p3t2c4: (skip)
+ * cogl_primitive_new_p3t2c4:
  * @context: A #CoglContext
  * @mode: A #CoglVerticesMode defining how to draw the vertices
  * @n_vertices: The number of vertices to read from @data and also
  *              the number of vertices to read when later drawing.
- * @data: (array length=n_vertices): (type Cogl.VertexP3T2C4): An
+ * @data: (array length=n_vertices) (element-type Cogl.VertexP3T2C4): An
  *        array of #CoglVertexP3T2C4 vertices
  *
  * Provides a convenient way to describe a primitive, such as a single
@@ -710,9 +710,9 @@ cogl_primitive_set_mode (CoglPrimitive *primitive,
                          CoglVerticesMode mode);
 
 /**
- * cogl_primitive_set_indices: (skip)
+ * cogl_primitive_set_indices:
  * @primitive: A #CoglPrimitive
- * @indices: A #CoglIndices array
+ * @indices: (array length=n_indices): A #CoglIndices array
  * @n_indices: The number of indices to reference when drawing
  *
  * Associates a sequence of #CoglIndices with the given @primitive.
@@ -740,11 +740,11 @@ cogl_primitive_set_indices (CoglPrimitive *primitive,
                             int n_indices);
 
 /**
- * cogl_primitive_get_indices: (skip)
+ * cogl_primitive_get_indices:
  * @primitive: A #CoglPrimitive
  *
- * Return value: (transfer none): the indices that were set with
- * cogl_primitive_set_indices() or %NULL if no indices were set.
+ * Return value: (transfer none) (nullable) (array): the indices that were set
+ * with cogl_primitive_set_indices() or %NULL if no indices were set.
  */
 COGL_EXPORT CoglIndices *
 cogl_primitive_get_indices (CoglPrimitive *primitive);
@@ -794,7 +794,7 @@ cogl_primitive_foreach_attribute (CoglPrimitive *primitive,
                                   void *user_data);
 
 /**
- * cogl_primitive_draw: (skip)
+ * cogl_primitive_draw:
  * @primitive: A #CoglPrimitive geometry object
  * @framebuffer: A destination #CoglFramebuffer
  * @pipeline: A #CoglPipeline state object
diff --git a/cogl/cogl/cogl-renderer.h b/cogl/cogl/cogl-renderer.h
index fe169dd01..d1b4789ea 100644
--- a/cogl/cogl/cogl-renderer.h
+++ b/cogl/cogl/cogl-renderer.h
@@ -179,7 +179,7 @@ COGL_EXPORT CoglWinsysID
 cogl_renderer_get_winsys_id (CoglRenderer *renderer);
 
 /**
- * cogl_renderer_check_onscreen_template: (skip)
+ * cogl_renderer_check_onscreen_template:
  * @renderer: A #CoglRenderer
  * @onscreen_template: A #CoglOnscreenTemplate
  * @error: A pointer to a #GError for reporting exceptions
@@ -375,7 +375,7 @@ cogl_renderer_create_dma_buf (CoglRenderer     *renderer,
 
 
 /**
- * cogl_renderer_is_dma_buf_supported: (skip)
+ * cogl_renderer_is_dma_buf_supported:
  * @renderer: A #CoglRenderer
  *
  * Returns: %TRUE if DMA buffers can be allocated
@@ -384,7 +384,7 @@ COGL_EXPORT gboolean
 cogl_renderer_is_dma_buf_supported (CoglRenderer *renderer);
 
 /**
- * cogl_renderer_bind_api: (skip)
+ * cogl_renderer_bind_api:
  */
 COGL_EXPORT void
 cogl_renderer_bind_api (CoglRenderer *renderer);
diff --git a/cogl/cogl/cogl-scanout.h b/cogl/cogl/cogl-scanout.h
index 2529eecb6..a62a7d706 100644
--- a/cogl/cogl/cogl-scanout.h
+++ b/cogl/cogl/cogl-scanout.h
@@ -68,6 +68,11 @@ gboolean cogl_scanout_blit_to_framebuffer (CoglScanout      *scanout,
 int cogl_scanout_buffer_get_width (CoglScanoutBuffer *scanout_buffer);
 int cogl_scanout_buffer_get_height (CoglScanoutBuffer *scanout_buffer);
 
+/**
+ * cogl_scanout_get_buffer:
+ *
+ * Returns: (transfer none): a #CoglScanoutBuffer
+ */
 COGL_EXPORT
 CoglScanoutBuffer * cogl_scanout_get_buffer (CoglScanout *scanout);
 
diff --git a/cogl/cogl/cogl-texture-2d-sliced.h b/cogl/cogl/cogl-texture-2d-sliced.h
index 79abfae2e..3effb10aa 100644
--- a/cogl/cogl/cogl-texture-2d-sliced.h
+++ b/cogl/cogl/cogl-texture-2d-sliced.h
@@ -83,7 +83,7 @@ COGL_EXPORT
 GType               cogl_texture_2d_sliced_get_type       (void) G_GNUC_CONST;
 
 /**
- * cogl_texture_2d_sliced_new_with_size: (skip)
+ * cogl_texture_2d_sliced_new_with_size:
  * @ctx: A #CoglContext
  * @width: The virtual width of your sliced texture.
  * @height: The virtual height of your sliced texture.
@@ -127,7 +127,7 @@ cogl_texture_2d_sliced_new_with_size (CoglContext *ctx,
                                       int max_waste);
 
 /**
- * cogl_texture_2d_sliced_new_from_data: (skip)
+ * cogl_texture_2d_sliced_new_from_data:
  * @ctx: A #CoglContext
  * @width: width of texture in pixels
  * @height: height of texture in pixels
@@ -139,7 +139,7 @@ cogl_texture_2d_sliced_new_with_size (CoglContext *ctx,
  * @rowstride: the memory offset in bytes between the start of each
  *    row in @data. A value of 0 will make Cogl automatically
  *    calculate @rowstride from @width and @format.
- * @data: pointer the memory region where the source buffer resides
+ * @data: (array): pointer the memory region where the source buffer resides
  * @error: A #GError to catch exceptional errors or %NULL
  *
  * Creates a new #CoglTexture2DSliced texture based on data residing
diff --git a/cogl/cogl/cogl-texture-2d.h b/cogl/cogl/cogl-texture-2d.h
index 467db2985..27797e632 100644
--- a/cogl/cogl/cogl-texture-2d.h
+++ b/cogl/cogl/cogl-texture-2d.h
@@ -80,7 +80,7 @@ typedef enum _CoglEglImageFlags
 } CoglEglImageFlags;
 
 /**
- * cogl_texture_2d_new_with_format: (skip)
+ * cogl_texture_2d_new_with_format:
  * @ctx: A #CoglContext
  * @width: Width of the texture to allocate
  * @height: Height of the texture to allocate
@@ -111,7 +111,7 @@ cogl_texture_2d_new_with_format (CoglContext *ctx,
                                  CoglPixelFormat format);
 
 /**
- * cogl_texture_2d_new_with_size: (skip)
+ * cogl_texture_2d_new_with_size:
  * @ctx: A #CoglContext
  * @width: Width of the texture to allocate
  * @height: Height of the texture to allocate
@@ -138,7 +138,7 @@ cogl_texture_2d_new_with_size (CoglContext *ctx,
                                int height);
 
 /**
- * cogl_texture_2d_new_from_data: (skip)
+ * cogl_texture_2d_new_from_data:
  * @ctx: A #CoglContext
  * @width: width of texture in pixels
  * @height: height of texture in pixels
@@ -146,7 +146,7 @@ cogl_texture_2d_new_with_size (CoglContext *ctx,
  * @rowstride: the memory offset in bytes between the starts of
  *    scanlines in @data. A value of 0 will make Cogl automatically
  *    calculate @rowstride from @width and @format.
- * @data: pointer the memory region where the source buffer resides
+ * @data: (array): pointer the memory region where the source buffer resides
  * @error: A #GError for exceptions
  *
  * Creates a low-level #CoglTexture2D texture based on data residing
diff --git a/cogl/cogl/cogl-texture.h b/cogl/cogl/cogl-texture.h
index 21daede56..e353b1a05 100644
--- a/cogl/cogl/cogl-texture.h
+++ b/cogl/cogl/cogl-texture.h
@@ -461,7 +461,7 @@ cogl_texture_allocate (CoglTexture *texture,
                        GError **error);
 
 /**
- * cogl_texture_is_get_data_supported: (skip)
+ * cogl_texture_is_get_data_supported:
  */
 COGL_EXPORT gboolean
 cogl_texture_is_get_data_supported (CoglTexture *texture);
diff --git a/cogl/cogl/cogl-types.h b/cogl/cogl/cogl-types.h
index 177406ded..589dab5d5 100644
--- a/cogl/cogl/cogl-types.h
+++ b/cogl/cogl/cogl-types.h
@@ -76,7 +76,7 @@ typedef struct _CoglColor               CoglColor;
 typedef struct _CoglTextureVertex       CoglTextureVertex;
 
 /**
- * CoglDmaBufHandle: (skip)
+ * CoglDmaBufHandle: (free-func cogl_dma_buf_handle_free)
  *
  * An opaque type that tracks the lifetime of a DMA buffer fd. Release
  * with cogl_dma_buf_handle_free().
diff --git a/cogl/cogl/meson.build b/cogl/cogl/meson.build
index 3299fcbac..eb690efce 100644
--- a/cogl/cogl/meson.build
+++ b/cogl/cogl/meson.build
@@ -8,34 +8,20 @@ cogl_deprecated_headers = [
 ]
 
 cogl_headers = [
-  'cogl-bitmap.h',
-  'cogl-color.h',
-  'cogl-context.h',
-  'cogl-frame-info.h',
-  'cogl-framebuffer.h',
-  'cogl-offscreen.h',
-  'cogl-onscreen.h',
-  'cogl-pipeline-layer-state.h',
-  'cogl-pipeline-state.h',
-  'cogl-pipeline.h',
-  'cogl-snippet.h',
-  'cogl-texture-2d-sliced.h',
-  'cogl-texture-2d.h',
-  'cogl-texture.h',
-  'cogl-trace.h',
-  'cogl-types.h',
   'cogl.h',
-  'cogl1-context.h',
-]
-
-cogl_nonintrospected_headers = [
   'cogl-atlas-texture.h',
   'cogl-attribute-buffer.h',
   'cogl-attribute.h',
+  'cogl-bitmap.h',
+  'cogl-color.h',
+  'cogl1-context.h',
+  'cogl-context.h',
   'cogl-depth-state.h',
   'cogl-display.h',
   'cogl-dma-buf-handle.h',
   'cogl-fence.h',
+  'cogl-framebuffer.h',
+  'cogl-frame-info.h',
   'cogl-glib-source.h',
   'cogl-graphene.h',
   'cogl-index-buffer.h',
@@ -43,16 +29,30 @@ cogl_nonintrospected_headers = [
   'cogl-macros.h',
   'cogl-matrix-stack.h',
   'cogl-meta-texture.h',
+  'cogl-offscreen.h',
+  'cogl-onscreen.h',
   'cogl-onscreen-template.h',
   'cogl-output.h',
+  'cogl-pipeline.h',
+  'cogl-pipeline-layer-state.h',
+  'cogl-pipeline-state.h',
   'cogl-pixel-buffer.h',
   'cogl-poll.h',
-  'cogl-primitive-texture.h',
   'cogl-primitive.h',
+  'cogl-primitive-texture.h',
   'cogl-renderer.h',
   'cogl-scanout.h',
+  'cogl-snippet.h',
   'cogl-sub-texture.h',
   'cogl-swap-chain.h',
+  'cogl-texture-2d.h',
+  'cogl-texture-2d-sliced.h',
+  'cogl-texture.h',
+  'cogl-trace.h',
+  'cogl-types.h',
+]
+
+cogl_nonintrospected_headers = [
 ]
 
 cogl_nodist_headers = [