GTimer: move docs from tmpl to .c

diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index 9cd6415..1edcd06 100644 (file)
--- a/docs/reference/glib/tmpl/.gitignore
+++ b/docs/reference/glib/tmpl/.gitignore
@@ -6,3 +6,4 @@ hash_tables.sgml
 option.sgml
 random_numbers.sgml
 threads.sgml
+timers.sgml

diff --git a/docs/reference/glib/tmpl/timers.sgml b/docs/reference/glib/tmpl/timers.sgml
deleted file mode 100644 (file)
index 8e3cfa8..0000000
--- a/docs/reference/glib/tmpl/timers.sgml
+++ /dev/null
@@ -1,110 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-Timers
-
-<!-- ##### SECTION Short_Description ##### -->
-keep track of elapsed time
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-#GTimer records a start time, and counts microseconds elapsed since that time.
-This is done somewhat differently on different platforms, and can be tricky to
-get exactly right, so #GTimer provides a portable/convenient interface.
-</para>
-<note><para>
-#GTimer uses a higher-quality clock when thread support is available. 
-Therefore, calling g_thread_init() while timers are running may lead to
-unreliable results. It is best to call g_thread_init() before starting
-any timers, if you are using threads at all.
-</para></note>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GTimer ##### -->
-<para>
-Opaque datatype that records a start time. 
-</para>
-
-
-<!-- ##### FUNCTION g_timer_new ##### -->
-<para>
-Creates a new timer, and starts timing (i.e. g_timer_start() is implicitly
-called for you).
-</para>
-
-@Returns: a new #GTimer.
-
-
-<!-- ##### FUNCTION g_timer_start ##### -->
-<para>
-Marks a start time, so that future calls to g_timer_elapsed() will report the
-time since g_timer_start() was called. g_timer_new() automatically marks the
-start time, so no need to call g_timer_start() immediately after creating the
-timer.
-</para>
-
-@timer: a #GTimer.
-
-
-<!-- ##### FUNCTION g_timer_stop ##### -->
-<para>
-Marks an end time, so calls to g_timer_elapsed() will return the difference
-between this end time and the start time.
-</para>
-
-@timer: a #GTimer.
-
-
-<!-- ##### FUNCTION g_timer_continue ##### -->
-<para>
-Resumes a timer that has previously been stopped with g_timer_stop().
-g_timer_stop() must be called before using this function.
-</para>
-
-@timer: a #GTimer.
-@Since: 2.4
-
-
-<!-- ##### FUNCTION g_timer_elapsed ##### -->
-<para>
-If @timer has been started but not stopped, obtains the time since the timer was
-started. If @timer has been stopped, obtains the elapsed time between the time
-it was started and the time it was stopped. The return value is the number of
-seconds elapsed, including any fractional part. The @microseconds
-out parameter is essentially useless.
-<warning><para>Calling initialization functions, in particular g_thread_init(),
-while a timer is running will cause invalid return values from this function.
-</para></warning>
-</para>
-
-@timer: a #GTimer.
-@microseconds: return location for the fractional part of seconds elapsed, 
-  in microseconds (that is, the total number of microseconds elapsed, modulo 
-   1000000), or %NULL
-@Returns: seconds elapsed as a floating point value, including 
-  any fractional part.
-
-
-<!-- ##### FUNCTION g_timer_reset ##### -->
-<para>
-This function is useless; it's fine to call g_timer_start() on an
-already-started timer to reset the start time, so g_timer_reset() serves no
-purpose.
-</para>
-
-@timer: a #GTimer.
-
-
-<!-- ##### FUNCTION g_timer_destroy ##### -->
-<para>
-Destroys a timer, freeing associated resources.
-</para>
-
-@timer: a #GTimer to destroy.
-
-

diff --git a/glib/gtimer.c b/glib/gtimer.c
index cd6a082..4e8397c 100644 (file)
--- a/glib/gtimer.c
+++ b/glib/gtimer.c
@@ -51,10 +51,33 @@
 #include "gthread.h"
 #include "galias.h"
 
+/**
+ * SECTION: timers
+ * @title: Timers
+ * @short_description: keep track of elapsed time
+ *
+ * #GTimer records a start time, and counts microseconds elapsed since
+ * that time. This is done somewhat differently on different platforms,
+ * and can be tricky to get exactly right, so #GTimer provides a
+ * portable/convenient interface.
+ *
+ * <note><para>
+ *  #GTimer uses a higher-quality clock when thread support is available.
+ *  Therefore, calling g_thread_init() while timers are running may lead to
+ *  unreliable results. It is best to call g_thread_init() before starting any
+ *  timers, if you are using threads at all.
+ * </para></note>
+ **/
+
 #define G_NSEC_PER_SEC 1000000000
 
 #define GETTIME(v) (v = g_thread_gettime ())
 
+/**
+ * GTimer:
+ *
+ * Opaque datatype that records a start time.
+ **/
 struct _GTimer
 {
   guint64 start;
@@ -63,7 +86,13 @@ struct _GTimer
   guint active : 1;
 };
 
-
+/**
+ * g_timer_new:
+ * @Returns: a new #GTimer.
+ *
+ * Creates a new timer, and starts timing (i.e. g_timer_start() is
+ * implicitly called for you).
+ **/
 GTimer*
 g_timer_new (void)
 {
@@ -77,6 +106,12 @@ g_timer_new (void)
   return timer;
 }
 
+/**
+ * g_timer_destroy:
+ * @timer: a #GTimer to destroy.
+ *
+ * Destroys a timer, freeing associated resources.
+ **/
 void
 g_timer_destroy (GTimer *timer)
 {
@@ -85,6 +120,15 @@ g_timer_destroy (GTimer *timer)
   g_free (timer);
 }
 
+/**
+ * g_timer_start:
+ * @timer: a #GTimer.
+ *
+ * Marks a start time, so that future calls to g_timer_elapsed() will
+ * report the time since g_timer_start() was called. g_timer_new()
+ * automatically marks the start time, so no need to call
+ * g_timer_start() immediately after creating the timer.
+ **/
 void
 g_timer_start (GTimer *timer)
 {
@@ -95,6 +139,13 @@ g_timer_start (GTimer *timer)
   GETTIME (timer->start);
 }
 
+/**
+ * g_timer_stop:
+ * @timer: a #GTimer.
+ *
+ * Marks an end time, so calls to g_timer_elapsed() will return the
+ * difference between this end time and the start time.
+ **/
 void
 g_timer_stop (GTimer *timer)
 {
@@ -105,6 +156,14 @@ g_timer_stop (GTimer *timer)
   GETTIME (timer->end);
 }
 
+/**
+ * g_timer_reset:
+ * @timer: a #GTimer.
+ *
+ * This function is useless; it's fine to call g_timer_start() on an
+ * already-started timer to reset the start time, so g_timer_reset()
+ * serves no purpose.
+ **/
 void
 g_timer_reset (GTimer *timer)
 {
@@ -113,6 +172,15 @@ g_timer_reset (GTimer *timer)
   GETTIME (timer->start);
 }
 
+/**
+ * g_timer_continue:
+ * @timer: a #GTimer.
+ * @Since: 2.4
+ *
+ * Resumes a timer that has previously been stopped with
+ * g_timer_stop(). g_timer_stop() must be called before using this
+ * function.
+ **/
 void
 g_timer_continue (GTimer *timer)
 {
@@ -135,6 +203,27 @@ g_timer_continue (GTimer *timer)
   timer->active = TRUE;
 }
 
+/**
+ * g_timer_elapsed:
+ * @timer: a #GTimer.
+ * @microseconds: return location for the fractional part of seconds
+ *                elapsed, in microseconds (that is, the total number
+ *                of microseconds elapsed, modulo 1000000), or %NULL
+ * @Returns: seconds elapsed as a floating point value, including any
+ *           fractional part.
+ *
+ * If @timer has been started but not stopped, obtains the time since
+ * the timer was started. If @timer has been stopped, obtains the
+ * elapsed time between the time it was started and the time it was
+ * stopped. The return value is the number of seconds elapsed,
+ * including any fractional part. The @microseconds out parameter is
+ * essentially useless.
+ *
+ * <warning><para>
+ *  Calling initialization functions, in particular g_thread_init(), while a
+ *  timer is running will cause invalid return values from this function.
+ * </para></warning>
+ **/
 gdouble
 g_timer_elapsed (GTimer *timer,
                 gulong *microseconds)