GNOME.org
 

[glib] Drop the warnings.sgml template

commit 4c64e75ec59317cf36d2bb9765c56477acf2acd7
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Jul 19 20:40:28 2011 -0400

    Drop the warnings.sgml template

 docs/reference/glib/tmpl/.gitignore    |    1 +
 docs/reference/glib/tmpl/warnings.sgml |  236 --------------------------------
 glib/gbacktrace.c                      |   63 +++++++++
 glib/gbacktrace.h                      |   18 +--
 glib/gmessages.c                       |  124 +++++++++++++----
 glib/gmessages.h                       |   81 +++++++++--
 6 files changed, 238 insertions(+), 285 deletions(-)
---
diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index e2c7359..8ecb027 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/glib/gbacktrace.c b/glib/gbacktrace.c
index ae16ef8..227d704 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 43a0c46..0ee3efd 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 337d19a..43b958f 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 9acaec6..5863419 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 */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]