[gtk+] GdkFrameTimings: add documentation

[Owen Taylor <otaylor src gnome org>]

commit c37de57f14d57ece9d0dd80a01a33641d71def93
Author: Owen W. Taylor <otaylor fishsoup net>
Date:   Tue Feb 12 18:26:17 2013 -0500

    GdkFrameTimings: add documentation

 gdk/gdkframetimings.c |  114 +++++++++++++++++++++++++++++++++++++++++++++++++
 gdk/gdkframetimings.h |   10 ++++
 2 files changed, 124 insertions(+), 0 deletions(-)
---
diff --git a/gdk/gdkframetimings.c b/gdk/gdkframetimings.c
index deb2932..5afdfae 100644
--- a/gdk/gdkframetimings.c
+++ b/gdk/gdkframetimings.c
@@ -19,6 +19,19 @@
 
 #include "gdkframeclockprivate.h"
 
+/**
+ * SECTION:frametimings
+ * @Short_description: Object holding timing information for a single frame
+ * @Title: Frame timings
+ *
+ * A #GdkFrameTimings object holds timing information for a single frame
+ * of the application's displays. To retrieve #GdkFrameTimings objects,
+ * use gdk_frame_clock_get_timings() or gdk_frame_clock_get_current_timings().
+ * The information in #GdkFrameTimings is useful for precise synchronization
+ * of video with the event or audio streams, and for measuring
+ * quality metrics for the application's display, such as latency and jitter.
+ */
+
 G_DEFINE_BOXED_TYPE (GdkFrameTimings, gdk_frame_timings,
                      gdk_frame_timings_ref,
                      gdk_frame_timings_unref)
@@ -35,6 +48,15 @@ _gdk_frame_timings_new (gint64 frame_counter)
   return timings;
 }
 
+/**
+ * gdk_frame_timings_ref:
+ * @timings: a #GdkFrameTimings
+ *
+ * Increases the reference count of @timings.
+ *
+ * Returns: @timings
+ * Since: 3.8
+ */
 GdkFrameTimings *
 gdk_frame_timings_ref (GdkFrameTimings *timings)
 {
@@ -45,6 +67,15 @@ gdk_frame_timings_ref (GdkFrameTimings *timings)
   return timings;
 }
 
+/**
+ * gdk_frame_timings_unref:
+ * @timings: a #GdkFrameTimings
+ *
+ * Decreases the reference count of @timings. If @timings
+ * is no longer referenced, it will be freed.
+ *
+ * Since: 3.8
+ */
 void
 gdk_frame_timings_unref (GdkFrameTimings *timings)
 {
@@ -58,12 +89,40 @@ gdk_frame_timings_unref (GdkFrameTimings *timings)
     }
 }
 
+/**
+ * gdk_frame_timings_get_frame_counter:
+ * @timings: a #GdkFrameTimings
+ *
+ * Gets the frame counter value of the #GdkFrameClock when this
+ * this frame was drawn.
+ *
+ * Returns: the frame counter value for this frame
+ * Since: 3.8
+ */
 gint64
 gdk_frame_timings_get_frame_counter (GdkFrameTimings *timings)
 {
   return timings->frame_counter;
 }
 
+/**
+ * gdk_frame_timings_complete:
+ * @timings: a #GdkFrameTimings
+ *
+ * The timing information in a #GdkFrameTimings is filled in
+ * incrementally as the frame as drawn and passed off to the
+ * window system for processing and display to the user. The
+ * accessor functions for #GdkFrameTimings can return 0 to
+ * indicate an unavailable value for two reasons: either because
+ * the information is not yet available, or because it isn't
+ * available at all. Once gdk_frame_timings_complete() returns
+ * %TRUE for a frame, you can be certain that no further values
+ * will become available and be stored in the #GdkFrameTimings.
+ *
+ * Returns: %TRUE if all information that will be available
+ *  for the frame has been filled in.
+ * Since: 3.8
+ */
 gboolean
 gdk_frame_timings_get_complete (GdkFrameTimings *timings)
 {
@@ -72,6 +131,17 @@ gdk_frame_timings_get_complete (GdkFrameTimings *timings)
   return timings->complete;
 }
 
+/**
+ * gdk_frame_timings_get_frame_time:
+ * @timings: A #GdkFrameTimings
+ *
+ * Returns the frame time for the frame. This is the time value
+ * that is typically used to time animations for the frame. See
+ * gdk_frame_clock_get_frame_time().
+ *
+ * Returns: the frame time for the frame, in the timescale
+ *  of g_get_monotonic_time()
+ */
 gint64
 gdk_frame_timings_get_frame_time (GdkFrameTimings *timings)
 {
@@ -80,6 +150,18 @@ gdk_frame_timings_get_frame_time (GdkFrameTimings *timings)
   return timings->frame_time;
 }
 
+/**
+ * gdk_frame_timings_get_presentation_time:
+ * @timings: a #GdkFrameTimings
+ *
+ * Reurns the presentation time. This is the time at which the frame
+ * became visible to the user.
+ *
+ * Returns: the time the frame was displayed to the user, in the
+ *  timescale of g_get_monotonic_time(), or 0 if no presentation
+ *  time is available. See gdk_frame_timings_get_complete()
+ * Since: 3.8
+ */
 gint64
 gdk_frame_timings_get_presentation_time (GdkFrameTimings *timings)
 {
@@ -88,6 +170,25 @@ gdk_frame_timings_get_presentation_time (GdkFrameTimings *timings)
   return timings->presentation_time;
 }
 
+/**
+ * gdk_frame_timings_get_predicted_presentation_time:
+ * @timings: a #GdkFrameTimings
+ *
+ * Gets the predicted time at which this frame will be displayed. Although
+ * no predicted time may be available, if one is available, it will
+ * be available while the frame is being generated, in contrast to
+ * gdk_frame_timings_get_presentation_time(), which is only available
+ * after the frame has been presented. In general, if you are simply
+ * animating, you should use gdk_frame_clock_get_frame_time() rather
+ * than this function, but this function is useful for applications
+ * that want exact control over latency. For example, a movie player
+ * may want this information for Audio/Video synchronization.
+ *
+ * Returns: The predicted time at which the frame will be presented,
+ *  in the timescale of g_get_monotonic_time(), or 0 if no predicted
+ *  presentation time is available.
+ * Since: 3.8
+ */
 gint64
 gdk_frame_timings_get_predicted_presentation_time (GdkFrameTimings *timings)
 {
@@ -96,6 +197,19 @@ gdk_frame_timings_get_predicted_presentation_time (GdkFrameTimings *timings)
   return timings->predicted_presentation_time;
 }
 
+/**
+ * gdk_frame_timings_get_refresh_interval:
+ * @timings: a #GdkFrameTimings
+ *
+ * Gets the natural interval between presentation times for
+ * the display that this frame was displayed on. Frame presentation
+ * usually happens during the "vertical blanking interval".
+ *
+ * Returns: the refresh interval of the display, in microseconds,
+ *  or 0 if the refresh interval is not available.
+ *  See gdk_frame_timings_get_complete().
+ * Since: 3.8
+ */
 gint64
 gdk_frame_timings_get_refresh_interval (GdkFrameTimings *timings)
 {
diff --git a/gdk/gdkframetimings.h b/gdk/gdkframetimings.h
index 0fb1e20..b345667 100644
--- a/gdk/gdkframetimings.h
+++ b/gdk/gdkframetimings.h
@@ -23,22 +23,32 @@
 #define __GDK_FRAME_TIMINGS_H__
 
 #include <glib-object.h>
+#include <gdk/gdkversionmacros.h>
 
 G_BEGIN_DECLS
 
 typedef struct _GdkFrameTimings GdkFrameTimings;
 
+GDK_AVAILABLE_IN_3_8
 GType            gdk_frame_timings_get_type (void) G_GNUC_CONST;
 
+GDK_AVAILABLE_IN_3_8
 GdkFrameTimings *gdk_frame_timings_ref   (GdkFrameTimings *timings);
+GDK_AVAILABLE_IN_3_8
 void             gdk_frame_timings_unref (GdkFrameTimings *timings);
 
+GDK_AVAILABLE_IN_3_8
 gint64           gdk_frame_timings_get_frame_counter     (GdkFrameTimings *timings);
+GDK_AVAILABLE_IN_3_8
 gboolean         gdk_frame_timings_get_complete          (GdkFrameTimings *timings);
+GDK_AVAILABLE_IN_3_8
 gint64           gdk_frame_timings_get_frame_time        (GdkFrameTimings *timings);
+GDK_AVAILABLE_IN_3_8
 gint64           gdk_frame_timings_get_presentation_time (GdkFrameTimings *timings);
+GDK_AVAILABLE_IN_3_8
 gint64           gdk_frame_timings_get_refresh_interval  (GdkFrameTimings *timings);
 
+GDK_AVAILABLE_IN_3_8
 gint64           gdk_frame_timings_get_predicted_presentation_time (GdkFrameTimings *timings);
 
 G_END_DECLS