Drop the warnings.sgml template

6 files changed, 238 insertions, 285 deletions

diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index e2c73597c..8ecb0272c 100644
--- a/docs/reference/glib/tmpl/.gitignore
+++ b/docs/reference/glib/tmpl/.gitignore
@@ -46,3 +46,4 @@ timers.sgml
 timezone.sgml
 unicode.sgml
 version.sgml
+warnings.sgml
diff --git a/docs/reference/glib/tmpl/warnings.sgml b/docs/reference/glib/tmpl/warnings.sgml
deleted file mode 100644
index 6c2aad782..000000000
--- a/docs/reference/glib/tmpl/warnings.sgml
+++ /dev/null
@@ -1,236 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-Message Output and Debugging Functions
-
-<!-- ##### SECTION Short_Description ##### -->
-functions to output messages and help debug applications
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-These functions provide support for outputting messages.
-</para>
-<para>
-The <function>g_return</function> family of macros (g_return_if_fail(), 
-g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached())
-should only be used for programming errors, a typical use case is
-checking for invalid parameters at the beginning of a public function.
-They should not be used if you just mean "if (error) return", they
-should only be used if you mean "if (bug in program) return".
-The program behavior is generally considered undefined after one of these 
-checks fails. They are not intended for normal control flow, only to
-give a perhaps-helpful warning before giving up. 
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### FUNCTION g_print ##### -->
-<para>
-Outputs a formatted message via the print handler.
-The default print handler simply outputs the message to stdout.
-</para>
-<para>
-g_print() should not be used from within libraries for debugging messages,
-since it may be redirected by applications to special purpose message
-windows or even files.
-Instead, libraries should use g_log(), or the convenience functions
-g_message(), g_warning() and g_error().
-</para>
-
-@format: the message format. See the printf() documentation.
-@Varargs: the parameters to insert into the format string.
-
-
-<!-- ##### FUNCTION g_set_print_handler ##### -->
-<para>
-Sets the print handler.
-Any messages passed to g_print() will be output via the new handler.
-The default handler simply outputs the message to stdout.
-By providing your own handler you can redirect the output, to a GTK+
-widget or a log file for example.
-</para>
-
-@func: the new print handler.
-@Returns: the old print handler.
-
-
-<!-- ##### USER_FUNCTION GPrintFunc ##### -->
-<para>
-Specifies the type of the print handler functions.
-These are called with the complete formatted string to output.
-</para>
-
-@string: the message to be output.
-
-
-<!-- ##### FUNCTION g_printerr ##### -->
-<para>
-Outputs a formatted message via the error message handler.
-The default handler simply outputs the message to stderr.
-</para>
-<para>
-g_printerr() should not be used from within libraries. Instead g_log() should
-be used, or the convenience functions g_message(), g_warning() and g_error().
-</para>
-
-@format: the message format. See the printf() documentation.
-@Varargs: the parameters to insert into the format string.
-
-
-<!-- ##### FUNCTION g_set_printerr_handler ##### -->
-<para>
-Sets the handler for printing error messages.
-Any messages passed to g_printerr() will be output via the new handler.
-The default handler simply outputs the message to stderr.
-By providing your own handler you can redirect the output, to a GTK+
-widget or a log file for example.
-</para>
-
-@func: the new error message handler.
-@Returns: the old error message handler.
-
-
-<!-- ##### MACRO g_return_if_fail ##### -->
-<para>
-Returns from the current function if the expression is not true.
-If the expression evaluates to %FALSE, a critical message is logged and
-the function returns. This can only be used in functions which do not return
-a value.
-</para>
-
-@expr: the expression to check.
-
-
-<!-- ##### MACRO g_return_val_if_fail ##### -->
-<para>
-Returns from the current function, returning the value @val, if the expression
-is not true.
-If the expression evaluates to %FALSE, a critical message is logged and
-@val is returned.
-</para>
-
-@expr: the expression to check.
-@val: the value to return from the current function if the expression is not
-true.
-
-
-<!-- ##### MACRO g_return_if_reached ##### -->
-<para>
-Logs a critical message and returns from the current function. 
-This can only be used in functions which do not return a value.
-</para>
-
-
-
-<!-- ##### MACRO g_return_val_if_reached ##### -->
-<para>
-Logs a critical message and returns @val. 
-</para>
-
-@val: the value to return from the current function.
-
-
-<!-- ##### MACRO g_warn_if_fail ##### -->
-<para>
-Logs a warning if the expression is not true.
-</para>
-
-@expr: the expression to check
-@Since: 2.16
-
-
-<!-- ##### MACRO g_warn_if_reached ##### -->
-<para>
-Logs a critical warning.
-</para>
-
-@Since: 2.16
-
-
-<!-- ##### FUNCTION g_on_error_query ##### -->
-<para>
-Prompts the user with <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>.
-This function is intended to be used for debugging use only. The following
-example shows how it can be used together with the g_log() functions.
-</para>
-<informalexample><programlisting>
-&num;include &lt;glib.h&gt;
-
-static void 
-log_handler (const gchar   *log_domain,
-	     GLogLevelFlags log_level,
-	     const gchar   *message,
-	     gpointer       user_data)
-{
-  g_log_default_handler (log_domain, log_level, message, user_data);
-
-  g_on_error_query (MY_PROGRAM_NAME);
-}
-
-int main (int argc, char *argv[])
-{
-  g_log_set_handler (MY_LOG_DOMAIN,
-		     G_LOG_LEVEL_WARNING | 
-                     G_LOG_LEVEL_ERROR | 
-                     G_LOG_LEVEL_CRITICAL,
-		     log_handler,
-		     NULL);
-
- /* ... */  
-</programlisting></informalexample>
-<para>
-If [E]xit is selected, the application terminates with a call to
-<function>_exit(0)</function>.
-</para>
-<para>
-If [H]alt is selected, the application enters an infinite loop.
-The infinite loop can only be stopped by killing the application,
-or by setting #glib_on_error_halt to %FALSE (possibly via a debugger).
-</para>
-<para>
-If [S]tack trace is selected, g_on_error_stack_trace() is called. This
-invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
-The prompt is then shown again.
-</para>
-<para>
-If [P]roceed is selected, the function returns.
-</para>
-<para>
-This function may cause different actions on non-UNIX platforms.
-</para>
-
-@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
-If @prg_name is %NULL, g_get_prgname() is called to get the program name
-(which will work correctly if gdk_init() or gtk_init() has been called).
-
-
-<!-- ##### FUNCTION g_on_error_stack_trace ##### -->
-<para>
-Invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
-Called by g_on_error_query() when the [S]tack trace option is selected.
-</para>
-<para>
-This function may cause different actions on non-UNIX platforms.
-</para>
-
-@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
-If @prg_name is %NULL, g_get_prgname() is called to get the program name
-(which will work correctly if gdk_init() or gtk_init() has been called).
-
-
-<!-- ##### MACRO G_BREAKPOINT ##### -->
-<para>
-Inserts a breakpoint instruction into the code.  On x86 and alpha systems
-this is implemented as a soft interrupt and on other architectures it raises
-a %SIGTRAP signal.
-</para>
-
-
-
diff --git a/glib/gbacktrace.c b/glib/gbacktrace.c
index ae16ef869..227d70426 100644
--- a/glib/gbacktrace.c
+++ b/glib/gbacktrace.c
@@ -91,6 +91,56 @@ static void stack_trace (char **args);
 extern volatile gboolean glib_on_error_halt;
 volatile gboolean glib_on_error_halt = TRUE;
 
+/**
+ * g_on_error_query:
+ * @prg_name: the program name, needed by <command>gdb</command>
+ *     for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname()
+ *     is called to get the program name (which will work correctly if
+ *     gdk_init() or gtk_init() has been called)
+ *
+ * Prompts the user with
+ * <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>.
+ * This function is intended to be used for debugging use only.
+ * The following example shows how it can be used together with
+ * the g_log() functions.
+ *
+ * |[
+ * &num;include &lt;glib.h&gt;
+ *
+ * static void
+ * log_handler (const gchar   *log_domain,
+ *              GLogLevelFlags log_level,
+ *              const gchar   *message,
+ *              gpointer       user_data)
+ * {
+ *   g_log_default_handler (log_domain, log_level, message, user_data);
+ *
+ *   g_on_error_query (MY_PROGRAM_NAME);
+ * }
+ *
+ * int
+ * main (int argc, char *argv[])
+ * {
+ *   g_log_set_handler (MY_LOG_DOMAIN,
+ *                      G_LOG_LEVEL_WARNING |
+ *                      G_LOG_LEVEL_ERROR |
+ *                      G_LOG_LEVEL_CRITICAL,
+ *                      log_handler,
+ *                      NULL);
+ *   /&ast; ... &ast;/
+ * ]|
+ *
+ * If [E]xit is selected, the application terminates with a call
+ * to <literal>_exit(0)</literal>.
+ *
+ * If [S]tack trace is selected, g_on_error_stack_trace() is called.
+ * This invokes <command>gdb</command>, which attaches to the current
+ * process and shows a stack trace. The prompt is then shown again.
+ *
+ * If [P]roceed is selected, the function returns.
+ *
+ * This function may cause different actions on non-UNIX platforms.
+ */
 void
 g_on_error_query (const gchar *prg_name)
 {
@@ -160,6 +210,19 @@ g_on_error_query (const gchar *prg_name)
 #endif
 }
 
+/**
+ * g_on_error_stack_trace:
+ * @prg_name: the program name, needed by <command>gdb</command>
+ *     for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname()
+ *     is called to get the program name (which will work correctly if
+ *     gdk_init() or gtk_init() has been called)
+ *
+ * Invokes <command>gdb</command>, which attaches to the current
+ * process and shows a stack trace. Called by g_on_error_query()
+ * when the [S]tack trace option is selected.
+ *
+ * This function may cause different actions on non-UNIX platforms.
+ */
 void
 g_on_error_stack_trace (const gchar *prg_name)
 {
diff --git a/glib/gbacktrace.h b/glib/gbacktrace.h
index 43a0c46a2..0ee3efd2f 100644
--- a/glib/gbacktrace.h
+++ b/glib/gbacktrace.h
@@ -36,20 +36,16 @@
 
 G_BEGIN_DECLS
 
-/* Fatal error handlers.
- * g_on_error_query() will prompt the user to either
- * [E]xit, [H]alt, [P]roceed or show [S]tack trace.
- * g_on_error_stack_trace() invokes gdb, which attaches to the current
- * process and shows a stack trace.
- * These function may cause different actions on non-unix platforms.
- * The prg_name arg is required by gdb to find the executable, if it is
- * passed as NULL, g_on_error_query() will try g_get_prgname().
- */
 void g_on_error_query (const gchar *prg_name);
 void g_on_error_stack_trace (const gchar *prg_name);
 
-/* Hacker macro to place breakpoints for selected machines.
- * Actual use is strongly discouraged of course ;)
+/**
+ * G_BREAKPOINT:
+ *
+ * Inserts a breakpoint instruction into the code.
+ *
+ * On x86 and alpha systems this is implemented as a soft interrupt
+ * and on other architectures it raises a %SIGTRAP signal.
  */
 #if (defined (__i386__) || defined (__x86_64__)) && defined (__GNUC__) && __GNUC__ >= 2
 #  define G_BREAKPOINT()        G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END
diff --git a/glib/gmessages.c b/glib/gmessages.c
index 337d19a50..43b958fb0 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -28,6 +28,24 @@
  * MT safe
  */
 
+/**
+ * SECTION:warnings
+ * @Title: Message Output and Debugging Functions
+ * @Short_description: functions to output messages and help debug applications
+ *
+ * These functions provide support for outputting messages.
+ *
+ * The <function>g_return</function> family of macros (g_return_if_fail(),
+ * g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached())
+ * should only be used for programming errors, a typical use case is
+ * checking for invalid parameters at the beginning of a public function.
+ * They should not be used if you just mean "if (error) return", they
+ * should only be used if you mean "if (bug in program) return".
+ * The program behavior is generally considered undefined after one
+ * of these checks fails. They are not intended for normal control
+ * flow, only to give a perhaps-helpful warning before giving up.
+ */
+
 #include "config.h"
 
 #include <stdlib.h>
@@ -986,37 +1004,65 @@ g_log_default_handler (const gchar   *log_domain,
   g_free (string);
 }
 
+/**
+ * g_set_print_handler:
+ * @func: the new print handler
+ *
+ * Sets the print handler.
+ *
+ * Any messages passed to g_print() will be output via
+ * the new handler. The default handler simply outputs
+ * the message to stdout. By providing your own handler
+ * you can redirect the output, to a GTK+ widget or a
+ * log file for example.
+ *
+ * Returns: the old print handler
+ */
 GPrintFunc
 g_set_print_handler (GPrintFunc func)
 {
   GPrintFunc old_print_func;
-  
+
   g_mutex_lock (g_messages_lock);
   old_print_func = glib_print_func;
   glib_print_func = func;
   g_mutex_unlock (g_messages_lock);
-  
+
   return old_print_func;
 }
 
+/**
+ * g_print:
+ * @format: the message format. See the printf() documentation
+ * @Varargs: the parameters to insert into the format string
+ *
+ * Outputs a formatted message via the print handler.
+ * The default print handler simply outputs the message to stdout.
+ *
+ * g_print() should not be used from within libraries for debugging
+ * messages, since it may be redirected by applications to special
+ * purpose message windows or even files. Instead, libraries should
+ * use g_log(), or the convenience functions g_message(), g_warning()
+ * and g_error().
+ */
 void
 g_print (const gchar *format,
-	 ...)
+         ...)
 {
   va_list args;
   gchar *string;
   GPrintFunc local_glib_print_func;
-  
+
   g_return_if_fail (format != NULL);
-  
+
   va_start (args, format);
   string = g_strdup_vprintf (format, args);
   va_end (args);
-  
+
   g_mutex_lock (g_messages_lock);
   local_glib_print_func = glib_print_func;
   g_mutex_unlock (g_messages_lock);
-  
+
   if (local_glib_print_func)
     local_glib_print_func (string);
   else
@@ -1024,50 +1070,76 @@ g_print (const gchar *format,
       const gchar *charset;
 
       if (g_get_charset (&charset))
-	fputs (string, stdout); /* charset is UTF-8 already */
+        fputs (string, stdout); /* charset is UTF-8 already */
       else
-	{
-	  gchar *lstring = strdup_convert (string, charset);
+        {
+          gchar *lstring = strdup_convert (string, charset);
 
-	  fputs (lstring, stdout);
-	  g_free (lstring);
-	}
+          fputs (lstring, stdout);
+          g_free (lstring);
+        }
       fflush (stdout);
     }
   g_free (string);
 }
 
+/**
+ * g_set_printerr_handler:
+ * @func: the new error message handler
+ *
+ * Sets the handler for printing error messages.
+ *
+ * Any messages passed to g_printerr() will be output via
+ * the new handler. The default handler simply outputs the
+ * message to stderr. By providing your own handler you can
+ * redirect the output, to a GTK+ widget or a log file for
+ * example.
+ *
+ * Returns: the old error message handler
+ */
 GPrintFunc
 g_set_printerr_handler (GPrintFunc func)
 {
   GPrintFunc old_printerr_func;
-  
+
   g_mutex_lock (g_messages_lock);
   old_printerr_func = glib_printerr_func;
   glib_printerr_func = func;
   g_mutex_unlock (g_messages_lock);
-  
+
   return old_printerr_func;
 }
 
+/**
+ * g_printerr:
+ * @format: the message format. See the printf() documentation
+ * @Varargs: the parameters to insert into the format string
+ *
+ * Outputs a formatted message via the error message handler.
+ * The default handler simply outputs the message to stderr.
+ *
+ * g_printerr() should not be used from within libraries.
+ * Instead g_log() should be used, or the convenience functions
+ * g_message(), g_warning() and g_error().
+ */
 void
 g_printerr (const gchar *format,
-	    ...)
+            ...)
 {
   va_list args;
   gchar *string;
   GPrintFunc local_glib_printerr_func;
-  
+
   g_return_if_fail (format != NULL);
-  
+
   va_start (args, format);
   string = g_strdup_vprintf (format, args);
   va_end (args);
-  
+
   g_mutex_lock (g_messages_lock);
   local_glib_printerr_func = glib_printerr_func;
   g_mutex_unlock (g_messages_lock);
-  
+
   if (local_glib_printerr_func)
     local_glib_printerr_func (string);
   else
@@ -1075,14 +1147,14 @@ g_printerr (const gchar *format,
       const gchar *charset;
 
       if (g_get_charset (&charset))
-	fputs (string, stderr); /* charset is UTF-8 already */
+        fputs (string, stderr); /* charset is UTF-8 already */
       else
-	{
-	  gchar *lstring = strdup_convert (string, charset);
+        {
+          gchar *lstring = strdup_convert (string, charset);
 
-	  fputs (lstring, stderr);
-	  g_free (lstring);
-	}
+          fputs (lstring, stderr);
+          g_free (lstring);
+        }
       fflush (stderr);
     }
   g_free (string);
diff --git a/glib/gmessages.h b/glib/gmessages.h
index 9acaec637..586341995 100644
--- a/glib/gmessages.h
+++ b/glib/gmessages.h
@@ -226,6 +226,13 @@ g_debug (const gchar *format,
 }
 #endif  /* !__GNUC__ */
 
+/**
+ * GPrintFunc:
+ * @string: the message to output
+ *
+ * Specifies the type of the print handler functions.
+ * These are called with the complete formatted string to output.
+ */
 typedef void    (*GPrintFunc)           (const gchar    *string);
 void            g_print                 (const gchar    *format,
                                          ...) G_GNUC_PRINTF (1, 2);
@@ -234,23 +241,73 @@ void            g_printerr              (const gchar    *format,
                                          ...) G_GNUC_PRINTF (1, 2);
 GPrintFunc      g_set_printerr_handler  (GPrintFunc      func);
 
+/**
+ * g_warn_if_reached:
+ *
+ * Logs a critical warning.
+ *
+ * Since: 2.16
+ */
+#define g_warn_if_reached() \
+  do { \
+    g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, NULL); \
+  } while (0)
+
+/**
+ * g_warn_if_fail:
+ * @expr: the expression to check
+ *
+ * Logs a warning if the expression is not true.
+ *
+ * Since: 2.16
+ */
+#define g_warn_if_fail(expr) \
+  do { \
+    if G_LIKELY (expr) ; \
+    else g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, #expr); \
+  } while (0)
+
+#ifdef G_DISABLE_CHECKS
 
-/* Provide macros for graceful error handling.
- * The "return" macros will return from the current function.
- * Two different definitions are given for the macros in
- * order to support gcc's __PRETTY_FUNCTION__ capability.
+/**
+ * g_return_if_fail:
+ * @expr: the expression to check
+ *
+ * Returns from the current function if the expression
+ * is not true. If the expression evaluates to %FALSE,
+ * a critical message is logged and the function returns.
+ * This can only be used in functions which do not return
+ * a value.
  */
+#define g_return_if_fail(expr) G_STMT_START{ (void)0; }G_STMT_END
 
-#define g_warn_if_reached()     do { g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, NULL); } while (0)
-#define g_warn_if_fail(expr)    do { if G_LIKELY (expr) ; else \
-                                       g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, #expr); } while (0)
+/**
+ * g_return_val_if_fail:
+ * @expr: the expression to check
+ * @val: the value to return from the current function
+ *       if the expression is not true
+ *
+ * Returns from the current function, returning the value @val,
+ * if the expression is not true. If the expression evaluates
+ * to %FALSE, a critical message is logged and @val is returned.
+ */
+#define g_return_val_if_fail(expr,val) G_STMT_START{ (void)0; }G_STMT_END
 
-#ifdef G_DISABLE_CHECKS
+/**
+ * g_return_if_reached:
+ *
+ * Logs a critical message and returns from the current function.
+ * This can only be used in functions which do not return a value.
+ */
+#define g_return_if_reached() G_STMT_START{ return; }G_STMT_END
 
-#define g_return_if_fail(expr)			G_STMT_START{ (void)0; }G_STMT_END
-#define g_return_val_if_fail(expr,val)		G_STMT_START{ (void)0; }G_STMT_END
-#define g_return_if_reached()			G_STMT_START{ return; }G_STMT_END
-#define g_return_val_if_reached(val)		G_STMT_START{ return (val); }G_STMT_END
+/**
+ * g_return_val_if_reached:
+ * @val: the value to return from the current function
+ *
+ * Logs a critical message and returns @val.
+ */
+#define g_return_val_if_reached(val) G_STMT_START{ return (val); }G_STMT_END
 
 #else /* !G_DISABLE_CHECKS */