gl: misc docs fixes/additions

18 files changed, 231 insertions, 32 deletions

diff --git a/gst-libs/gst/gl/gstglapi.c b/gst-libs/gst/gl/gstglapi.c
index 3bee14b01..f79a6e49b 100644
--- a/gst-libs/gst/gl/gstglapi.c
+++ b/gst-libs/gst/gl/gstglapi.c
@@ -120,9 +120,9 @@ gst_gl_api_from_string (const gchar * apis_s)
 
 /**
  * gst_gl_platform_to_string:
- * @api: a #GstGLPlatform to stringify
+ * @platform: a #GstGLPlatform to stringify
  *
- * Returns: A space seperated string of the OpenGL platforms enabled in @api
+ * Returns: A space seperated string of the OpenGL platforms enabled in @platform
  */
 gchar *
 gst_gl_platform_to_string (GstGLPlatform platform)
diff --git a/gst-libs/gst/gl/gstglapi.h b/gst-libs/gst/gl/gstglapi.h
index ab1a203f5..be381130c 100644
--- a/gst-libs/gst/gl/gstglapi.h
+++ b/gst-libs/gst/gl/gstglapi.h
@@ -79,6 +79,16 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GstGLAPI:
+ * @GST_GL_API_NONE: no API
+ * @GST_GL_API_OPENGL: Desktop OpenGL up to and including 3.1.  The
+ *                    compatibility profile when the OpenGL version is >= 3.2
+ * @GST_GL_API_OPENGL3: Desktop OpenGL >= 3.2 core profile
+ * @GST_GL_API_GLES1: OpenGL ES 1.x
+ * @GST_GL_API_GLES2: OpenGL ES 2.x and 3.x
+ * @GST_GL_API_ANY: Any OpenGL API
+ */
 typedef enum {
   GST_GL_API_NONE = 0,
   GST_GL_API_OPENGL = (1 << 0),
@@ -89,11 +99,45 @@ typedef enum {
   GST_GL_API_ANY = G_MAXUINT32
 } GstGLAPI;
 
+/**
+ * GST_GL_API_OPENGL_NAME:
+ *
+ * The name for %GST_GL_API_OPENGL used in various places
+ */
 #define GST_GL_API_OPENGL_NAME "opengl"
+
+/**
+ * GST_GL_API_OPENGL3_NAME:
+ *
+ * The name for %GST_GL_API_OPENGL3 used in various places
+ */
 #define GST_GL_API_OPENGL3_NAME "opengl3"
+
+/**
+ * GST_GL_API_GLES1_NAME:
+ *
+ * The name for %GST_GL_API_GLES1 used in various places
+ */
 #define GST_GL_API_GLES1_NAME "gles1"
+
+/**
+ * GST_GL_API_GLES2_NAME:
+ *
+ * The name for %GST_GL_API_GLES2 used in various places
+ */
 #define GST_GL_API_GLES2_NAME "gles2"
 
+/**
+ * GstGLPlatform:
+ * @GST_GL_PLATFORM_NONE: no platform
+ * @GST_GL_PLATFORM_EGL: the EGL platform used primarily with the X11, wayland
+ *                      and android window systems as well as on embedded Linux
+ * @GST_GL_PLATFORM_GLX: the GLX platform used primarily with the X11 window system
+ * @GST_GL_PLATFORM_WGL: the WGL platform used primarily on Windows
+ * @GST_GL_PLATFORM_CGL: the CGL platform used primarily on OS X
+ * @GST_GL_PLATFORM_EAGL: the EAGL platform used primarily on iOS
+ * @GST_GL_PLATFORM_ANY: any OpenGL platform
+ */
 typedef enum
 {
   GST_GL_PLATFORM_NONE = 0,
@@ -125,7 +169,7 @@ typedef struct _GstGLFuncs
 gchar * gst_gl_api_to_string (GstGLAPI api);
 GstGLAPI gst_gl_api_from_string (const gchar * api_s);
 
-gchar * gst_gl_platform_to_string (GstGLPlatform api);
+gchar * gst_gl_platform_to_string (GstGLPlatform platform);
 GstGLPlatform gst_gl_platform_from_string (const gchar * platform_s);
 
 G_END_DECLS
diff --git a/gst-libs/gst/gl/gstglbasefilter.c b/gst-libs/gst/gl/gstglbasefilter.c
index b45b4eaee..556cd43a1 100644
--- a/gst-libs/gst/gl/gstglbasefilter.c
+++ b/gst-libs/gst/gl/gstglbasefilter.c
@@ -26,6 +26,18 @@
 
 #include <gst/gl/gl.h>
 
+/**
+ * SECTION:gstglbasefilter
+ * @short_description: #GstBaseTransform subclass for transformin OpenGL resources
+ * @title: GstGLBaseFilter
+ * @see_also: #GstBaseTransform
+ *
+ * #GstGLBaseFilter handles the nitty gritty details of retrieving an OpenGL
+ * context.  It also provided some wrappers around #GstBaseTransform's
+ * start(), stop() and set_caps() virtual methods that ensure an OpenGL context
+ * is available and current in the calling thread.
+ */
+
 #define GST_CAT_DEFAULT gst_gl_base_filter_debug
 GST_DEBUG_CATEGORY_STATIC (GST_CAT_DEFAULT);
 
diff --git a/gst-libs/gst/gl/gstglbasefilter.h b/gst-libs/gst/gl/gstglbasefilter.h
index 84f7a96e3..fa16d0701 100644
--- a/gst-libs/gst/gl/gstglbasefilter.h
+++ b/gst-libs/gst/gl/gstglbasefilter.h
@@ -41,12 +41,11 @@ GType gst_gl_base_filter_get_type(void);
 
 /**
  * GstGLBaseFilter:
- * @base_transform: parent #GstBaseTransform
+ * @parent: parent #GstBaseTransform
  * @display: the currently configured #GstGLDisplay
  * @context: the currently configured #GstGLContext
- *
- * #GstGLBaseFilter is a base class that provides the logic of getting the
- * GL context from the pipeline.
+ * @in_caps: the currently configured input #GstCaps
+ * @out_caps: the currently configured output #GstCaps
  */
 struct _GstGLBaseFilter
 {
@@ -66,7 +65,8 @@ struct _GstGLBaseFilter
 
 /**
  * GstGLBaseFilterClass:
- * @base_transform_class: parent class
+ * @parent_class: parent class
+ * @supported_gl_api: the logical-OR of #GstGLAPI's supported by this element
  * @gl_start: called in the GL thread to setup the element GL state.
  * @gl_stop: called in the GL thread to setup the element GL state.
  * @gl_set_caps: called in the GL thread when caps are set on @filter.
@@ -80,6 +80,7 @@ struct _GstGLBaseFilterClass
   void     (*gl_stop)           (GstGLBaseFilter *filter);
   gboolean (*gl_set_caps)       (GstGLBaseFilter *filter, GstCaps * incaps, GstCaps * outcaps);
 
+  /* <private> */
   gpointer _padding[GST_PADDING];
 };
 
diff --git a/gst-libs/gst/gl/gstglbufferpool.c b/gst-libs/gst/gl/gstglbufferpool.c
index c419ad5f7..90536b037 100644
--- a/gst-libs/gst/gl/gstglbufferpool.c
+++ b/gst-libs/gst/gl/gstglbufferpool.c
@@ -458,6 +458,12 @@ gst_gl_buffer_pool_finalize (GObject * object)
   priv->gl_params = NULL;
 }
 
+/**
+ * gst_buffer_pool_config_get_gl_allocation_params:
+ * @config: a buffer pool config
+ *
+ * Returns: (transfer full): the currently set #GstGLAllocationParams or %NULL
+ */
 GstGLAllocationParams *
 gst_buffer_pool_config_get_gl_allocation_params (GstStructure * config)
 {
@@ -470,6 +476,13 @@ gst_buffer_pool_config_get_gl_allocation_params (GstStructure * config)
   return ret;
 }
 
+/**
+ * gst_buffer_pool_config_set_gl_allocation_params:
+ * @config: a buffer pool config
+ * @params: (transfer none): a #GstGLAllocationParams
+ *
+ * Sets @params on @config
+ */
 void
 gst_buffer_pool_config_set_gl_allocation_params (GstStructure * config,
     GstGLAllocationParams * params)
diff --git a/gst-libs/gst/gl/gstglcolorconvert.c b/gst-libs/gst/gl/gstglcolorconvert.c
index afb6aff5c..eb3b4a8f3 100644
--- a/gst-libs/gst/gl/gstglcolorconvert.c
+++ b/gst-libs/gst/gl/gstglcolorconvert.c
@@ -31,15 +31,12 @@
 /**
  * SECTION:gstglcolorconvert
  * @short_description: an object that converts between color spaces/formats
- * @see_also: #GstGLUpload, #GstGLDownload, #GstGLMemory
+ * @see_also: #GstGLUpload, #GstGLMemory, #GstGLBaseMemory
  *
  * #GstGLColorConvert is an object that converts between color spaces and/or
  * formats using OpenGL Shaders.
  *
  * A #GstGLColorConvert can be created with gst_gl_color_convert_new().
- *
- * For handling stride scaling in the shader, see
- * gst_gl_color_convert_set_texture_scaling().
  */
 
 #define USING_OPENGL(context) (gst_gl_context_check_gl_version (context, GST_GL_API_OPENGL, 1, 0))
diff --git a/gst-libs/gst/gl/gstglcontext.h b/gst-libs/gst/gl/gstglcontext.h
index 4d917323d..5cbc8ad84 100644
--- a/gst-libs/gst/gl/gstglcontext.h
+++ b/gst-libs/gst/gl/gstglcontext.h
@@ -136,7 +136,7 @@ gboolean      gst_gl_context_create           (GstGLContext *context, GstGLConte
 void          gst_gl_context_destroy          (GstGLContext *context);
 
 gpointer      gst_gl_context_default_get_proc_address (GstGLAPI gl_api, const gchar *name);
-gpointer      gst_gl_context_get_proc_address_with_platform (GstGLPlatform, GstGLAPI gl_api, const gchar *name);
+gpointer      gst_gl_context_get_proc_address_with_platform (GstGLPlatform context_type, GstGLAPI gl_api, const gchar *name);
 
 gboolean      gst_gl_context_set_window (GstGLContext *context, GstGLWindow *window);
 GstGLWindow * gst_gl_context_get_window (GstGLContext *context);
@@ -145,7 +145,7 @@ void          gst_gl_context_get_gl_version (GstGLContext *context, gint *maj, g
 gboolean      gst_gl_context_check_gl_version (GstGLContext * context, GstGLAPI api, gint maj, gint min);
 gboolean      gst_gl_context_check_feature (GstGLContext *context, const gchar *feature);
 
-guintptr      gst_gl_context_get_current_gl_context     (GstGLPlatform platform);
+guintptr      gst_gl_context_get_current_gl_context     (GstGLPlatform context_type);
 GstGLAPI      gst_gl_context_get_current_gl_api         (GstGLPlatform platform, guint *major, guint *minor);
 
 gboolean      gst_gl_context_is_shared                  (GstGLContext * context);
diff --git a/gst-libs/gst/gl/gstgldebug.c b/gst-libs/gst/gl/gstgldebug.c
index 2b9a01fc6..5b89bf64c 100644
--- a/gst-libs/gst/gl/gstgldebug.c
+++ b/gst-libs/gst/gl/gstgldebug.c
@@ -27,6 +27,13 @@
 #include <glib/gprintf.h>
 #include <string.h>
 
+/**
+ * SECTION:gstgldebug
+ * @short_description: helper routines for dealing with OpenGL debugging
+ * @title: OpenGL debugging
+ * @see_also: #GstGLContext
+ */
+
 #define ASYNC_DEBUG_FILLED (1 << 0)
 #define ASYNC_DEBUG_FROZEN (1 << 1)
 
@@ -119,6 +126,15 @@ _free_async_debug_data (GstGLAsyncDebug * ad)
   }
 }
 
+/**
+ * gst_gl_async_debug_init:
+ * @ad: a #GstGLAsyncDebug
+ *
+ * Initialize @ad.  Intended for use with #GstGLAsyncDebug's that are embedded
+ * in other structs.
+ *
+ * Since: 1.8
+ */
 void
 gst_gl_async_debug_init (GstGLAsyncDebug * ad)
 {
@@ -127,6 +143,13 @@ gst_gl_async_debug_init (GstGLAsyncDebug * ad)
   memset (ad, 0, sizeof (*ad));
 }
 
+/**
+ * gst_gl_async_debug_unset:
+ * @ad: a #GstGLAsyncDebug
+ *
+ * Unset any dynamically allocated data.  Intended for use with
+ * #GstGLAsyncDebug's that are embedded in other structs.
+ */
 void
 gst_gl_async_debug_unset (GstGLAsyncDebug * ad)
 {
@@ -138,12 +161,30 @@ gst_gl_async_debug_unset (GstGLAsyncDebug * ad)
     ad->notify (ad->user_data);
 }
 
+/**
+ * gst_gl_async_debug_new:
+ * @ad: a #GstGLAsyncDebug
+ *
+ * Free with gst_gl_async_debug_free()
+ *
+ * Returns: a new #GstGLAsyncDebug
+ *
+ * Since: 1.8
+ */
 GstGLAsyncDebug *
 gst_gl_async_debug_new (void)
 {
   return g_new0 (GstGLAsyncDebug, 1);
 }
 
+/**
+ * gst_gl_async_debug_free:
+ * @ad: a #GstGLAsyncDebug
+ *
+ * Frees @ad
+ *
+ * Since: 1.8
+ */
 void
 gst_gl_async_debug_free (GstGLAsyncDebug * ad)
 {
@@ -159,6 +200,8 @@ gst_gl_async_debug_free (GstGLAsyncDebug * ad)
  * gst_gl_async_debug_output_log_msg() will not output any messages but
  * subsequent calls to gst_gl_async_debug_store_log_msg() will overwrite previous
  * messages.
+ *
+ * Since: 1.8
  */
 void
 gst_gl_async_debug_freeze (GstGLAsyncDebug * ad)
@@ -171,6 +214,8 @@ gst_gl_async_debug_freeze (GstGLAsyncDebug * ad)
  * @ad: a #GstGLAsyncDebug
  *
  * unfreeze the debug output.  See gst_gl_async_debug_freeze() for what freezing means
+ *
+ * Since: 1.8
  */
 void
 gst_gl_async_debug_thaw (GstGLAsyncDebug * ad)
@@ -325,6 +370,17 @@ _gst_gl_debug_enable (GstGLContext * context)
   }
 }
 
+/**
+ * gst_gl_insert_debug_marker:
+ * @context: a #GstGLContext
+ * @format: a printf-style format string
+ * @...: arguments form @format
+ *
+ * Inserts a marker into a GL debug stream.  Requires the 'gldebugmarker'
+ * debug category to be at least %GST_LEVEL_FIXME.
+ *
+ * Since: 1.8
+ */
 void
 gst_gl_insert_debug_marker (GstGLContext * context, const gchar * format, ...)
 {
@@ -373,6 +429,8 @@ gst_gl_insert_debug_marker (GstGLContext * context, const gchar * format, ...)
  * @varargs: the list of arguments for @format
  *
  * Stores a debug message for later output by gst_gl_async_debug_output_log_msg()
+ *
+ * Since: 1.8
  */
 void
 gst_gl_async_debug_store_log_msg_valist (GstGLAsyncDebug * ad,
@@ -438,6 +496,8 @@ gst_gl_async_debug_output_log_msg (GstGLAsyncDebug * ad)
  * @...: the list of arguments for @format
  *
  * Stores a debug message for later output by gst_gl_async_debug_output_log_msg()
+ *
+ * Since: 1.8
  */
 void
 gst_gl_async_debug_store_log_msg (GstGLAsyncDebug * ad, GstDebugCategory * cat,
diff --git a/gst-libs/gst/gl/gstgldebug.h b/gst-libs/gst/gl/gstgldebug.h
index 5b936d0ea..f568a2b91 100644
--- a/gst-libs/gst/gl/gstgldebug.h
+++ b/gst-libs/gst/gl/gstgldebug.h
@@ -65,9 +65,6 @@ void                gst_gl_async_debug_thaw                     (GstGLAsyncDebug
  * @ad: the #GstGLAsyncDebug to store the message in
  * @cat: the #GstDebugCategory to output the message in
  * @level: the #GstLevel
- * @file: the file where the debug message originates from
- * @function: the function where the debug message originates from
- * @line: the line in @file where the debug message originates from
  * @object: (allow-none): a #GObject to associate with the debug message
  * @format: a printf style format string
  * @varargs: the list of arguments for @format
@@ -83,9 +80,6 @@ void                gst_gl_async_debug_thaw                     (GstGLAsyncDebug
  * @ad: the #GstGLAsyncDebug to store the message in
  * @cat: the #GstDebugCategory to output the message in
  * @level: the #GstLevel
- * @file: the file where the debug message originates from
- * @function: the function where the debug message originates from
- * @line: the line in @file where the debug message originates from
  * @object: (allow-none): a #GObject to associate with the debug message
  * @format: a printf style format string
  * @...: the list of arguments for @format
diff --git a/gst-libs/gst/gl/gstgldisplay.h b/gst-libs/gst/gl/gstgldisplay.h
index 9341884e1..7f49a4432 100644
--- a/gst-libs/gst/gl/gstgldisplay.h
+++ b/gst-libs/gst/gl/gstgldisplay.h
@@ -40,6 +40,17 @@ GType gst_gl_display_get_type (void);
 #define GST_GL_DISPLAY_CAST(obj)        ((GstGLDisplay*)(obj))
 #define GST_GL_DISPLAY_GET_CLASS(o)     (G_TYPE_INSTANCE_GET_CLASS((o), GST_TYPE_GL_DISPLAY, GstGLDisplayClass))
 
+/**
+ * GstGLDisplayType:
+ * @GST_GL_DISPLAY_TYPE_NONE: no display type
+ * @GST_GL_DISPLAY_TYPE_X11: X11 display
+ * @GST_GL_DISPLAY_TYPE_WAYLAND: Wayland display
+ * @GST_GL_DISPLAY_TYPE_COCOA: Cocoa display
+ * @GST_GL_DISPLAY_TYPE_WIN32: Win32 display
+ * @GST_GL_DISPLAY_TYPE_DISPMANX: Dispmanx display
+ * @GST_GL_DISPLAY_TYPE_EGL: EGL display
+ * @GST_GL_DISPLAY_TYPE_ANY: any display type
+ */
 typedef enum
 {
   GST_GL_DISPLAY_TYPE_NONE = 0,
@@ -84,7 +95,7 @@ GstGLDisplay *gst_gl_display_new (void);
 guintptr         gst_gl_display_get_handle             (GstGLDisplay * display);
 GstGLDisplayType gst_gl_display_get_handle_type        (GstGLDisplay * display);
 void             gst_gl_display_filter_gl_api          (GstGLDisplay * display,
-                                                        GstGLAPI api);
+                                                        GstGLAPI gl_api);
 GstGLAPI         gst_gl_display_get_gl_api             (GstGLDisplay * display);
 GstGLAPI         gst_gl_display_get_gl_api_unlocked    (GstGLDisplay * display);
 
diff --git a/gst-libs/gst/gl/gstglshader.c b/gst-libs/gst/gl/gstglshader.c
index 56cb9ed7d..e7800b705 100644
--- a/gst-libs/gst/gl/gstglshader.c
+++ b/gst-libs/gst/gl/gstglshader.c
@@ -27,6 +27,12 @@
 #include "gstglshader.h"
 #include "gstglsl_private.h"
 
+/**
+ * SECTION:gstglshader
+ * @short_description: object representing an OpenGL shader program
+ * @see_also: #GstGLSLStage
+ */
+
 #ifndef GLhandleARB
 #define GLhandleARB GLuint
 #endif
@@ -261,6 +267,7 @@ _new_with_stages_va_list (GstGLContext * context, GError ** error,
  * gst_gl_shader_new_link_with_stages:
  * @context: a #GstGLContext
  * @error: a #GError
+ * @...: a NULL terminated list of #GstGLSLStage's
  *
  * Each stage will attempt to be compiled and attached to @shader.  Then
  * the shader will be linked. On error, %NULL will be returned and @error will
@@ -269,6 +276,8 @@ _new_with_stages_va_list (GstGLContext * context, GError ** error,
  * Note: must be called in the GL thread
  *
  * Returns: (transfer full): a new @shader with the specified stages.
+ *
+ * Since: 1.8
  */
 GstGLShader *
 gst_gl_shader_new_link_with_stages (GstGLContext * context, GError ** error,
@@ -294,6 +303,7 @@ gst_gl_shader_new_link_with_stages (GstGLContext * context, GError ** error,
  * gst_gl_shader_new_with_stages:
  * @context: a #GstGLContext
  * @error: a #GError
+ * @...: a NULL terminated list of #GstGLSLStage's
  *
  * Each stage will attempt to be compiled and attached to @shader.  On error,
  * %NULL will be returned and @error will contain the details of the error.
@@ -301,6 +311,8 @@ gst_gl_shader_new_link_with_stages (GstGLContext * context, GError ** error,
  * Note: must be called in the GL thread
  *
  * Returns: (transfer full): a new @shader with the specified stages.
+ *
+ * Since: 1.8
  */
 GstGLShader *
 gst_gl_shader_new_with_stages (GstGLContext * context, GError ** error, ...)
@@ -332,10 +344,13 @@ gst_gl_shader_new (GstGLContext * context)
 /**
  * gst_gl_shader_new_default:
  * @context: a #GstGLContext
+ * @error: a #GError that is filled on failure
  *
  * Note: must be called in the GL thread
  *
- * Returns: (transfer full): a default @shader
+ * Returns: (transfer full): a default @shader or %NULL on failure
+ *
+ * Since: 1.8
  */
 GstGLShader *
 gst_gl_shader_new_default (GstGLContext * context, GError ** error)
@@ -352,6 +367,8 @@ gst_gl_shader_new_default (GstGLContext * context, GError ** error)
  * Note: must be called in the GL thread
  *
  * Returns: whether @shader has been successfully linked
+ *
+ * Since: 1.8
  */
 gboolean
 gst_gl_shader_is_linked (GstGLShader * shader)
@@ -382,6 +399,8 @@ _ensure_program (GstGLShader * shader)
  * @shader: a #GstGLShader
  *
  * Returns: the GL program handle for this shader
+ *
+ * Since: 1.8
  */
 int
 gst_gl_shader_get_program_handle (GstGLShader * shader)
@@ -406,6 +425,8 @@ gst_gl_shader_get_program_handle (GstGLShader * shader)
  * to @shader with gst_gl_shader_attach() or gst_gl_shader_attach_unlocked().
  *
  * Note: must be called in the GL thread
+ *
+ * Since: 1.8
  */
 void
 gst_gl_shader_detach_unlocked (GstGLShader * shader, GstGLSLStage * stage)
@@ -459,6 +480,8 @@ gst_gl_shader_detach_unlocked (GstGLShader * shader, GstGLSLStage * stage)
  * to @shader with gst_gl_shader_attach() or gst_gl_shader_attach_unlocked().
  *
  * Note: must be called in the GL thread
+ *
+ * Since: 1.8
  */
 void
 gst_gl_shader_detach (GstGLShader * shader, GstGLSLStage * stage)
@@ -482,6 +505,8 @@ gst_gl_shader_detach (GstGLShader * shader, GstGLSLStage * stage)
  * Note: must be called in the GL thread
  *
  * Returns: whether @stage could be attached to @shader
+ *
+ * Since: 1.8
  */
 gboolean
 gst_gl_shader_attach_unlocked (GstGLShader * shader, GstGLSLStage * stage)
@@ -533,6 +558,8 @@ gst_gl_shader_attach_unlocked (GstGLShader * shader, GstGLSLStage * stage)
  * Note: must be called in the GL thread
  *
  * Returns: whether @stage could be attached to @shader
+ *
+ * Since: 1.8
  */
 gboolean
 gst_gl_shader_attach (GstGLShader * shader, GstGLSLStage * stage)
@@ -560,6 +587,8 @@ gst_gl_shader_attach (GstGLShader * shader, GstGLSLStage * stage)
  * Note: must be called in the GL thread
  *
  * Returns: whether @stage could be compiled and attached to @shader
+ *
+ * Since: 1.8
  */
 gboolean
 gst_gl_shader_compile_attach_stage (GstGLShader * shader, GstGLSLStage * stage,
@@ -590,6 +619,8 @@ gst_gl_shader_compile_attach_stage (GstGLShader * shader, GstGLSLStage * stage,
  * Note: must be called in the GL thread
  *
  * Returns: whether @shader could be linked together.
+ *
+ * Since: 1.8
  */
 gboolean
 gst_gl_shader_link (GstGLShader * shader, GError ** error)
@@ -683,6 +714,8 @@ gst_gl_shader_link (GstGLShader * shader, GError ** error)
  * Releases the shader and stages.
  *
  * Note: must be called in the GL thread
+ *
+ * Since: 1.8
  */
 void
 gst_gl_shader_release_unlocked (GstGLShader * shader)
@@ -718,6 +751,8 @@ gst_gl_shader_release_unlocked (GstGLShader * shader)
  * Releases the shader and stages.
  *
  * Note: must be called in the GL thread
+ *
+ * Since: 1.8
  */
 void
 gst_gl_shader_release (GstGLShader * shader)
@@ -755,7 +790,7 @@ gst_gl_shader_use (GstGLShader * shader)
 
 /**
  * gst_gl_context_clear_shader:
- * @shader: a #GstGLShader
+ * @context: a #GstGLContext
  *
  * Clear's the currently set shader from the GL state machine.
  *
diff --git a/gst-libs/gst/gl/gstglsl.c b/gst-libs/gst/gl/gstglsl.c
index 282662227..507455290 100644
--- a/gst-libs/gst/gl/gstglsl.c
+++ b/gst-libs/gst/gl/gstglsl.c
@@ -27,6 +27,12 @@
 #include "gstglsl.h"
 #include "gstglsl_private.h"
 
+/**
+ * SECTION:gstglsl
+ * @short_description: helpers for dealing with OpenGL shaders
+ * @see_also: #GstGLSLStage, #GstGLShader
+ */
+
 GQuark
 gst_glsl_error_quark (void)
 {
diff --git a/gst-libs/gst/gl/gstglslstage.c b/gst-libs/gst/gl/gstglslstage.c
index 581320126..caa5860bf 100644
--- a/gst-libs/gst/gl/gstglslstage.c
+++ b/gst-libs/gst/gl/gstglslstage.c
@@ -27,6 +27,15 @@
 #include "gstglslstage.h"
 #include "gstglsl_private.h"
 
+/**
+ * SECTION:gstglslstage
+ * @short_description: object for dealing with OpenGL shader stages
+ * @title: GstGLSLStage
+ * @see_also: #GstGLShader
+ *
+ * #GstGLSLStage holds and represents a single OpenGL shader stage.
+ */
+
 static const gchar *es2_version_header = "#version 100\n";
 
 GST_DEBUG_CATEGORY_STATIC (gst_glsl_stage_debug);
@@ -185,6 +194,10 @@ _ensure_shader (GstGLSLStage * stage)
  * gst_glsl_stage_new_with_strings:
  * @context: a #GstGLContext
  * @type: the GL enum shader stage type
+ * @version: the #GstGLSLVersion
+ * @profile: the #GstGLSLProfile
+ * @n_strings: the number of strings in @str
+ * @str: an array of strings concatted together to produce a shader
  *
  * Returns: (transfer full): a new #GstGLSLStage of the specified @type
  */
@@ -216,9 +229,12 @@ gst_glsl_stage_new_with_strings (GstGLContext * context, guint type,
 }
 
 /**
- * gst_glsl_stage_new_with_strings:
+ * gst_glsl_stage_new_with_string:
  * @context: a #GstGLContext
  * @type: the GL enum shader stage type
+ * @version: the #GstGLSLVersion
+ * @profile: the #GstGLSLProfile
+ * @str: a shader string
  *
  * Returns: (transfer full): a new #GstGLSLStage of the specified @type
  */
@@ -484,6 +500,7 @@ _compile_shader (GstGLContext * context, struct compile *data)
 /**
  * gst_glsl_stage_compile:
  * @stage: a #GstGLSLStage
+ * @error: a #GError to use on failure
  *
  * Returns: whether the compilation suceeded
  */
diff --git a/gst-libs/gst/gl/gstglslstage.h b/gst-libs/gst/gl/gstglslstage.h
index 69fbf2e41..31dcbec03 100644
--- a/gst-libs/gst/gl/gstglslstage.h
+++ b/gst-libs/gst/gl/gstglslstage.h
@@ -32,6 +32,11 @@ G_BEGIN_DECLS
 #define GST_IS_GLSL_STAGE_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE((k), GST_TYPE_GLSL_STAGE))
 #define GST_GLSL_STAGE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS((o), GST_TYPE_GLSL_STAGE, GstGLSLStageClass))
 
+/**
+ * GstGLSLStage:
+ *
+ * Opaque #GstGLSLStage struct
+ */
 struct _GstGLSLStage
 {
   /*< private >*/
@@ -44,11 +49,15 @@ struct _GstGLSLStage
   gpointer _padding[GST_PADDING];
 };
 
+/**
+ * GstGLSLStageClass:
+ *
+ * Opaque #GstGLSLStageClass struct
+ */
 struct _GstGLSLStageClass
 {
-  GstObjectClass parent;
-
   /*< private >*/
+  GstObjectClass parent;
 };
 
 GType          gst_glsl_stage_get_type          (void);
diff --git a/gst-libs/gst/gl/gstglupload.c b/gst-libs/gst/gl/gstglupload.c
index 16ed5eaab..eb25e15ac 100644
--- a/gst-libs/gst/gl/gstglupload.c
+++ b/gst-libs/gst/gl/gstglupload.c
@@ -1620,11 +1620,11 @@ _upload_find_method (GstGLUpload * upload)
 /**
  * gst_gl_upload_perform_with_buffer:
  * @upload: a #GstGLUpload
- * @buffer: a #GstBuffer
- * @outbuf_ptr: esulting buffer
+ * @buffer: input #GstBuffer
+ * @outbuf_ptr: resulting #GstBuffer
  *
  * Uploads @buffer using the transformation specified by
- * gst_gl_upload_set_caps().
+ * gst_gl_upload_set_caps() creating a new #GstBuffer in @outbuf_ptr.
  *
  * Returns: whether the upload was successful
  */
diff --git a/gst-libs/gst/gl/gstglupload.h b/gst-libs/gst/gl/gstglupload.h
index ed6dc6755..577c94b5d 100644
--- a/gst-libs/gst/gl/gstglupload.h
+++ b/gst-libs/gst/gl/gstglupload.h
@@ -98,7 +98,7 @@ void          gst_gl_upload_propose_allocation     (GstGLUpload * upload,
 
 GstGLUploadReturn gst_gl_upload_perform_with_buffer (GstGLUpload * upload,
                                                     GstBuffer * buffer,
-                                                    GstBuffer ** outbuf);
+                                                    GstBuffer ** outbuf_ptr);
 
 G_END_DECLS
 
diff --git a/gst-libs/gst/gl/gstglutils.c b/gst-libs/gst/gl/gstglutils.c
index 2b0104f53..0290efb40 100644
--- a/gst-libs/gst/gl/gstglutils.c
+++ b/gst-libs/gst/gl/gstglutils.c
@@ -952,7 +952,7 @@ gst_gl_caps_replace_all_caps_features (const GstCaps * caps,
  * gst_gl_value_get_texture_target_mask:
  * @value: an initialized #GValue of type G_TYPE_STRING
  *
- * See gst_gl_value_set_texture_target_mask() for what entails a mask
+ * See gst_gl_value_set_texture_target_from_mask() for what entails a mask
  *
  * Returns: the mask of #GstGLTextureTarget's in @value
  */
diff --git a/gst-libs/gst/gl/gstglviewconvert.c b/gst-libs/gst/gl/gstglviewconvert.c
index 9215eb021..7d44860d4 100644
--- a/gst-libs/gst/gl/gstglviewconvert.c
+++ b/gst-libs/gst/gl/gstglviewconvert.c
@@ -21,7 +21,7 @@
  */
 
 /**
- * SECTION:viewconvert
+ * SECTION:gstglviewconvert
  *
  * Convert stereoscopic/multiview video using fragment shaders.
  */