docs: Documentation fixes

Let's see if we can get a 100% coverage for Clutter too.

clutter/clutter-animatable.h

@@ -41,6 +41,15 @@ G_BEGIN_DECLS
 typedef struct _ClutterAnimatable               ClutterAnimatable; /* dummy typedef */
 typedef struct _ClutterAnimatableIface          ClutterAnimatableIface;
 
+/**
+ * ClutterAnimatable:
+ *
+ * #ClutterAnimatable is an opaque structure whose members cannot be directly
+ * accessed
+ *
+ * Since: 1.0
+ */
+
 /**
  * ClutterAnimatableIface:
  * @animate_property: virtual function for animating a property

clutter/clutter-animator.c

@@ -1351,7 +1351,8 @@ clutter_animator_get_keys (ClutterAnimator *animator,
 }
 
 /**
- * clutter_animator_remove:
+ * clutter_animator_remove_key:
+ * @animator: a #ClutterAnimator
  * @object: (allow-none): a #GObject to search for, or %NULL for all
  * @property_name: (allow-none): a specific property name to query for,
  *   or %NULL for all
@@ -1833,7 +1834,7 @@ clutter_animator_property_set_ease_in (ClutterAnimator *animator,
 
 
 /**
- * clutter_animator_property_set_interpolation:
+ * clutter_animator_property_get_interpolation:
  * @animator: a #ClutterAnimatorKey
  * @object: a #GObject
  * @property_name: the name of a property on object

clutter/clutter-box.c

@@ -17,6 +17,9 @@
  *
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Author:
+ *      Emmanuele Bassi <ebassi@linux.intel.com>
  */
 
 /**

clutter/clutter-box.h

@@ -1,3 +1,27 @@
+/*
+ * Clutter.
+ *
+ * An OpenGL based 'interactive canvas' library.
+ *
+ * Copyright (C) 2009,2010  Intel Corporation.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Author:
+ *      Emmanuele Bassi <ebassi@linux.intel.com>
+ */
+
 #if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
 #error "Only <clutter/clutter.h> can be included directly."
 #endif
@@ -22,16 +46,41 @@ typedef struct _ClutterBox              ClutterBox;
 typedef struct _ClutterBoxPrivate       ClutterBoxPrivate;
 typedef struct _ClutterBoxClass         ClutterBoxClass;
 
+/**
+ * ClutterBox:
+ *
+ * The #ClutterBox structure contains only private data and should
+ * be accessed using the provided API
+ *
+ * Since: 1.2
+ */
 struct _ClutterBox
 {
+  /*< private >*/
   ClutterActor parent_instance;
 
   ClutterBoxPrivate *priv;
 };
 
+/**
+ * ClutterBoxClass:
+ *
+ * The #ClutterBoxClass structure contains only private data
+ *
+ * Since: 1.2
+ */
 struct _ClutterBoxClass
 {
+  /*< private >*/
   ClutterActorClass parent_class;
+
+  /* padding, for future expansion */
+  void (*clutter_padding_1) (void);
+  void (*clutter_padding_2) (void);
+  void (*clutter_padding_3) (void);
+  void (*clutter_padding_4) (void);
+  void (*clutter_padding_5) (void);
+  void (*clutter_padding_6) (void);
 };
 
 GType clutter_box_get_type (void) G_GNUC_CONST;

clutter/clutter-container.h

@@ -44,6 +44,15 @@ G_BEGIN_DECLS
 
 typedef struct _ClutterContainerIface   ClutterContainerIface;
 
+/**
+ * ClutterContainer:
+ *
+ * #ClutterContainer is an opaque structure whose members cannot be directly
+ * accessed
+ *
+ * Since: 0.4
+ */
+
 /**
  * ClutterContainerIface:
  * @add: virtual function for adding an actor to the container. The

clutter/clutter-device-manager.h

@@ -46,8 +46,9 @@ typedef struct _ClutterDeviceManagerClass       ClutterDeviceManagerClass;
 /**
  * ClutterDeviceManager:
  *
- * The #ClutterDeviceManager structure contains only
+ * The #ClutterDeviceManager structure contains only private data
- * private data
+ *
+ * Since: 1.2
  */
 struct _ClutterDeviceManager
 {
@@ -57,6 +58,13 @@ struct _ClutterDeviceManager
   ClutterDeviceManagerPrivate *priv;
 };
 
+/**
+ * ClutterDeviceManagerClass:
+ *
+ * The #ClutterDeviceManagerClass structure contains only private data
+ *
+ * Since: 1.2
+ */
 struct _ClutterDeviceManagerClass
 {
   /*< private >*/
@@ -73,6 +81,7 @@ struct _ClutterDeviceManagerClass
   void                (* remove_device)   (ClutterDeviceManager   *manager,
                                            ClutterInputDevice     *device);
 
+  /* padding */
   gpointer _padding[8];
 };
 

clutter/clutter-media.h

@@ -42,6 +42,15 @@ G_BEGIN_DECLS
 typedef struct _ClutterMedia            ClutterMedia; /* dummy typedef */
 typedef struct _ClutterMediaIface       ClutterMediaIface;
 
+/**
+ * ClutterMedia:
+ *
+ * #ClutterMedia is an opaque structure whose members cannot be directly
+ * accessed
+ *
+ * Since: 0.2
+ */
+
 /**
  * ClutterMediaIface:
  * @eos: handler for the #ClutterMedia::eos signal

clutter/clutter-scriptable.h

@@ -43,6 +43,15 @@ G_BEGIN_DECLS
 typedef struct _ClutterScriptable               ClutterScriptable;
 typedef struct _ClutterScriptableIface          ClutterScriptableIface;
 
+/**
+ * ClutterScriptable:
+ *
+ * #ClutterScriptable is an opaque structure whose members cannot be directly
+ * accessed
+ *
+ * Since: 0.6
+ */
+
 /**
  * ClutterScriptableIface:
  * @set_id: virtual function for setting the id of a scriptable object

clutter/clutter-version.h.in

@@ -135,8 +135,46 @@ G_BEGIN_DECLS
  */
 #define CLUTTER_NO_FPU          CLUTTER_NO_FPU_MACRO_WAS_REMOVED
 
+/**
+ * clutter_major_version:
+ *
+ * The major component of the Clutter library version, e.g. 1 if the version
+ * is 1.2.3
+ *
+ * This value can be used for run-time version checks
+ *
+ * For a compile-time check, use %CLUTTER_MAJOR_VERSION
+ *
+ * Since: 1.2
+ */
 extern const guint clutter_major_version;
+
+/**
+ * clutter_minor_version:
+ *
+ * The minor component of the Clutter library version, e.g. 2 if the version
+ * is 1.2.3
+ *
+ * This value can be used for run-time version checks
+ *
+ * For a compile-time check, use %CLUTTER_MINOR_VERSION
+ *
+ * Since: 1.2
+ */
 extern const guint clutter_minor_version;
+
+/**
+ * clutter_micro_version:
+ *
+ * The micro component of the Clutter library version, e.g. 3 if the version
+ * is 1.2.3
+ *
+ * This value can be used for run-time version checks
+ *
+ * For a compile-time check, use %CLUTTER_MICRO_VERSION
+ *
+ * Since: 1.2
+ */
 extern const guint clutter_micro_version;
 
 gboolean clutter_check_version (guint major,

clutter/eglnative/clutter-backend-egl.c

@@ -244,6 +244,13 @@ _clutter_backend_impl_get_type (void)
   return clutter_backend_egl_get_type ();
 }
 
+/**
+ * clutter_egl_display:
+ *
+ * Retrieves the <structname>EGLDisplay</structname> used by Clutter
+ *
+ * Return value: the EGL display
+ */
 EGLDisplay
 clutter_egl_display (void)
 {

clutter/glx/clutter-glx-texture-pixmap.c

@@ -859,12 +859,17 @@ clutter_glx_texture_pixmap_class_init (ClutterGLXTexturePixmapClass *klass)
  * clutter_glx_texture_pixmap_using_extension:
  * @texture: A #ClutterGLXTexturePixmap
  *
- * Return value: A boolean indicating if the texture is using the
+ * Checks whether @texture is using the GLX_EXT_texture_from_pixmap
- * GLX_EXT_texture_from_pixmap OpenGL extension or falling back to
+ * extension; this extension can be optionally (though it is strongly
+ * encouraged) implemented as a zero-copy between a GLX pixmap and
+ * a GL texture.
+ *
+ * Return value: %TRUE if the texture is using the
+ *   GLX_EXT_texture_from_pixmap OpenGL extension or falling back to the
  *   slower software mechanism.
  *
  * Since: 0.8
- **/
+ */
 gboolean
 clutter_glx_texture_pixmap_using_extension (ClutterGLXTexturePixmap *texture)
 {
@@ -883,26 +888,26 @@ clutter_glx_texture_pixmap_using_extension (ClutterGLXTexturePixmap *texture)
  * clutter_glx_texture_pixmap_new_with_pixmap:
  * @pixmap: the X Pixmap to which this texture should be bound
  *
+ * Creates a new #ClutterGLXTexturePixmap for @pixmap
+ *
  * Return value: A new #ClutterGLXTexturePixmap bound to the given X Pixmap
  *
  * Since: 0.8
- **/
+ */
 ClutterActor *
 clutter_glx_texture_pixmap_new_with_pixmap (Pixmap pixmap)
 {
-  ClutterActor *actor;
+  return g_object_new (CLUTTER_GLX_TYPE_TEXTURE_PIXMAP,
-
-  actor = g_object_new (CLUTTER_GLX_TYPE_TEXTURE_PIXMAP,
                        "pixmap", pixmap,
                        NULL);
-
-  return actor;
 }
 
 /**
  * clutter_glx_texture_pixmap_new_with_window:
  * @window: the X window to which this texture should be bound
  *
+ * Creates a new #ClutterGLXTexturePixmap for @window
+ *
  * Return value: A new #ClutterGLXTexturePixmap bound to the given X window
  *
  * Since: 0.8
@@ -910,28 +915,22 @@ clutter_glx_texture_pixmap_new_with_pixmap (Pixmap pixmap)
 ClutterActor *
 clutter_glx_texture_pixmap_new_with_window (Window window)
 {
-  ClutterActor *actor;
+  return g_object_new (CLUTTER_GLX_TYPE_TEXTURE_PIXMAP,
-
-  actor = g_object_new (CLUTTER_GLX_TYPE_TEXTURE_PIXMAP,
                        "window", window,
                        NULL);
-
-  return actor;
 }
 
 /**
  * clutter_glx_texture_pixmap_new:
  *
+ * Creates a new, empty #ClutterGLXTexturePixmap
+ *
  * Return value: A new #ClutterGLXTexturePixmap
  *
  * Since: 0.8
- **/
+ */
 ClutterActor *
 clutter_glx_texture_pixmap_new (void)
 {
-  ClutterActor *actor;
+  return g_object_new (CLUTTER_GLX_TYPE_TEXTURE_PIXMAP, NULL);
-
-  actor = g_object_new (CLUTTER_GLX_TYPE_TEXTURE_PIXMAP, NULL);
-
-  return actor;
 }

clutter/glx/clutter-glx-texture-pixmap.h

@@ -45,13 +45,29 @@ typedef struct _ClutterGLXTexturePixmap        ClutterGLXTexturePixmap;
 typedef struct _ClutterGLXTexturePixmapClass   ClutterGLXTexturePixmapClass;
 typedef struct _ClutterGLXTexturePixmapPrivate ClutterGLXTexturePixmapPrivate;
 
+/**
+ * ClutterGLXTexturePixmapClass:
+ *
+ * The #ClutterGLXTexturePixmapClass structure contains only private data
+ *
+ * Since: 0.8
+ */
 struct _ClutterGLXTexturePixmapClass
 {
+  /*< private >*/
   ClutterX11TexturePixmapClass   parent_class;
 };
 
+/**
+ * ClutterGLXTexturePixmap:
+ *
+ * The #ClutterGLXTexturePixmap structure contains only private data
+ *
+ * Since: 0.8
+ */
 struct _ClutterGLXTexturePixmap
 {
+  /*< private >*/
   ClutterX11TexturePixmap         parent;
 
   ClutterGLXTexturePixmapPrivate *priv;

clutter/x11/clutter-backend-x11.c

@@ -751,6 +751,14 @@ clutter_x11_has_xinput (void)
 #endif
 }
 
+/**
+ * clutter_x11_has_composite_extension:
+ *
+ * Retrieves whether Clutter is running on an X11 server with the
+ * XComposite extension
+ *
+ * Return value: %TRUE if the XComposite extension is available
+ */
 gboolean
 clutter_x11_has_composite_extension (void)
 {

clutter/x11/clutter-x11-texture-pixmap.c

@@ -941,10 +941,13 @@ clutter_x11_texture_pixmap_update_area_real (ClutterX11TexturePixmap *texture,
 /**
  * clutter_x11_texture_pixmap_new:
  *
+ * Creates a new #ClutterX11TexturePixmap which can be used to display the
+ * contents of an X11 Pixmap inside a Clutter scene graph
+ *
  * Return value: A new #ClutterX11TexturePixmap
  *
  * Since: 0.8
- **/
+ */
 ClutterActor *
 clutter_x11_texture_pixmap_new (void)
 {
@@ -959,10 +962,12 @@ clutter_x11_texture_pixmap_new (void)
  * clutter_x11_texture_pixmap_new_with_pixmap:
  * @pixmap: the X Pixmap to which this texture should be bound
  *
+ * Creates a new #ClutterX11TexturePixmap for @pixmap
+ *
  * Return value: A new #ClutterX11TexturePixmap bound to the given X Pixmap
  *
  * Since: 0.8
- **/
+ */
 ClutterActor *
 clutter_x11_texture_pixmap_new_with_pixmap (Pixmap pixmap)
 {
@@ -979,6 +984,8 @@ clutter_x11_texture_pixmap_new_with_pixmap (Pixmap pixmap)
  * clutter_x11_texture_pixmap_new_with_window:
  * @window: the X window to which this texture should be bound
  *
+ * Creates a new #ClutterX11TexturePixmap for @window
+ *
  * Return value: A new #ClutterX11TexturePixmap bound to the given X window.
  *
  * Since: 0.8
@@ -1003,7 +1010,7 @@ clutter_x11_texture_pixmap_new_with_window (Window window)
  * Sets the X Pixmap to which the texture should be bound.
  *
  * Since: 0.8
- **/
+ */
 void
 clutter_x11_texture_pixmap_set_pixmap (ClutterX11TexturePixmap *texture,
                                        Pixmap                   pixmap)
@@ -1125,16 +1132,17 @@ clutter_x11_texture_pixmap_set_pixmap (ClutterX11TexturePixmap *texture,
  * clutter_x11_texture_pixmap_set_window:
  * @texture: the texture to bind
  * @window: the X window to which the texture should be bound
- * @automatic: TRUE is automatic window updates, FALSE for manual.
+ * @automatic: %TRUE for automatic window updates, %FALSE for manual.
  *
  * Sets up a suitable pixmap for the window, using the composite and damage
  * extensions if possible, and then calls
- * clutter_x11_texture_pixmap_set_pixmap(). If you want a window in a texture,
+ * clutter_x11_texture_pixmap_set_pixmap().
- * you probably want this function, or its older sister,
+ *
- * clutter_glx_texture_pixmap_set_window().
+ * If you want to display a window in a #ClutterTexture, you probably want
+ * this function, or its older sister, clutter_glx_texture_pixmap_set_window()
  *
  * Since: 0.8
- **/
+ */
 void
 clutter_x11_texture_pixmap_set_window (ClutterX11TexturePixmap *texture,
                                        Window                   window,
@@ -1226,7 +1234,7 @@ clutter_x11_texture_pixmap_set_window (ClutterX11TexturePixmap *texture,
  * pixmap's invalidation as the window changed size.
  *
  * Since: 0.8
- **/
+ */
 void
 clutter_x11_texture_pixmap_sync_window (ClutterX11TexturePixmap *texture)
 {
@@ -1363,6 +1371,16 @@ clutter_x11_texture_pixmap_update_area (ClutterX11TexturePixmap *texture,
   g_signal_emit (texture, signals[UPDATE_AREA], 0, x, y, width, height);
 }
 
+/**
+ * clutter_x11_texture_pixmap_set_automatic:
+ * @texture: a #ClutterX11TexturePixmap
+ * @setting: %TRUE to enable automatic updates
+ *
+ * Enables or disables the automatic updates ot @texture in case the backing
+ * pixmap or window is damaged
+ *
+ * Since: 0.8
+ */
 void
 clutter_x11_texture_pixmap_set_automatic (ClutterX11TexturePixmap *texture,
                                           gboolean                 setting)

clutter/x11/clutter-x11-texture-pixmap.h

@@ -44,10 +44,20 @@ typedef struct _ClutterX11TexturePixmap        ClutterX11TexturePixmap;
 typedef struct _ClutterX11TexturePixmapClass   ClutterX11TexturePixmapClass;
 typedef struct _ClutterX11TexturePixmapPrivate ClutterX11TexturePixmapPrivate;
 
+/**
+ * ClutterX11TexturePixmapClass:
+ * @update_area: virtual function for updating the area of the texture
+ *
+ * The #ClutterX11TexturePixmapClass structure contains only private data
+ *
+ * Since: 0.8
+ */
 struct _ClutterX11TexturePixmapClass
 {
+  /*< private >*/
   ClutterTextureClass    parent_class;
 
+  /*< public >*/
   void                  (*update_area)    (ClutterX11TexturePixmap *texture,
                                            gint                     x,
                                            gint                     y,
@@ -55,14 +65,22 @@ struct _ClutterX11TexturePixmapClass
                                            gint                     height);
 };
 
+/**
+ * ClutterX11TexturePixmap:
+ *
+ * The #ClutterX11TexturePixmap structure contains only private data
+ *
+ * Since: 0.8
+ */
 struct _ClutterX11TexturePixmap
 {
+  /*< private >*/
   ClutterTexture                  parent;
 
   ClutterX11TexturePixmapPrivate *priv;
 };
 
-GType clutter_x11_texture_pixmap_get_type (void);
+GType clutter_x11_texture_pixmap_get_type (void) G_GNUC_CONST;
 ClutterActor * clutter_x11_texture_pixmap_new (void);
 
 ClutterActor * clutter_x11_texture_pixmap_new_with_pixmap (Pixmap      pixmap);

clutter/x11/clutter-x11.h

@@ -65,6 +65,9 @@ typedef enum {
   CLUTTER_X11_FILTER_REMOVE
 } ClutterX11FilterReturn;
 
+/*
+ * This is an internal only enumeration; it should really be private
+ */
 typedef enum {
   CLUTTER_X11_XINPUT_KEY_PRESS_EVENT = 0,
   CLUTTER_X11_XINPUT_KEY_RELEASE_EVENT,
@@ -74,6 +77,9 @@ typedef enum {
   CLUTTER_X11_XINPUT_LAST_EVENT
 } ClutterX11XInputEventTypes;
 
+/*
+ * This is not used any more
+ */
 typedef struct _ClutterX11XInputDevice ClutterX11XInputDevice;
 
 /**
@@ -122,7 +128,7 @@ gboolean clutter_x11_has_event_retrieval (void);
 ClutterStage *clutter_x11_get_stage_from_window (Window win);
 
 #ifndef CLUTTER_DISABLE_DEPRECATED
-G_CONST_RETURN GSList* clutter_x11_get_input_devices (void);
+G_CONST_RETURN GSList* clutter_x11_get_input_devices (void) G_GNUC_DEPRECATED;
 #endif
 
 void     clutter_x11_enable_xinput (void);

doc/reference/clutter/Makefile.am

@@ -80,8 +80,6 @@ IGNORE_HFILES=\
 	clutter-script-private.h 	\
 	clutter-stage-window.h 		\
 	clutter-timeout-interval.h 	\
-	stamp-clutter-enum-types.h 	\
-	stamp-clutter-marshal.h 	\
 	cogl 				\
 	eglnative 			\
 	eglx 				\
@@ -90,8 +88,6 @@ IGNORE_HFILES=\
 	osx 				\
 	x11 				\
 	json 				\
-	pango 				\
-	sdl 				\
 	win32
 
 EXTRA_HFILES=\

doc/reference/clutter/clutter-sections.txt

@@ -1147,8 +1147,6 @@ clutter_x11_add_filter
 clutter_x11_remove_filter
 
 <SUBSECTION>
-ClutterX11XInputDevice
-ClutterX11XInputEventTypes
 clutter_x11_get_input_devices
 clutter_x11_has_xinput
 clutter_x11_enable_xinput
@@ -1176,6 +1174,8 @@ clutter_x11_texture_pixmap_get_type
 
 <SUBSECTION Private>
 ClutterX11TexturePixmapPrivate
+ClutterX11XInputDevice
+ClutterX11XInputEventTypes
 </SECTION>
 
 <SECTION>