project: document classes

src/gcal-debug.h.in

@@ -21,6 +21,18 @@
 
 #include <glib.h>
 
+/**
+ * SECTION:gcal-debug
+ * @short_description: Debugging macros
+ * @title:Debugging
+ * @stability:stable
+ *
+ * Macros used for tracing and debugging code. These
+ * are only valid when Calendar is compiled with tracing
+ * suppoer (pass `--enable-tracing` to the configure
+ * script to do that).
+ */
+
 G_BEGIN_DECLS
 
 #ifndef GCAL_ENABLE_TRACE
@@ -38,46 +50,158 @@ G_BEGIN_DECLS
 #endif
 
 #ifdef GCAL_ENABLE_TRACE
+
+/**
+ * GCAL_TRACE_MSG:
+ * @fmt: printf-like format of the message
+ * @...: arguments for @fmt
+ *
+ * Prints a trace message.
+ */
 # define GCAL_TRACE_MSG(fmt, ...)                                        \
    g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, "  MSG: %s():%d: " fmt,     \
          G_STRFUNC, __LINE__, ##__VA_ARGS__)
+
+/**
+ * GCAL_PROBE:
+ *
+ * Prints a probing message. Put this macro in the code when
+ * you want to check the program reaches a certain section
+ * of code.
+ */
 # define GCAL_PROBE                                                      \
    g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, "PROBE: %s():%d",           \
          G_STRFUNC, __LINE__)
+
+/**
+ * GCAL_TODO:
+ * @_msg: the message to print
+ *
+ * Prints a TODO message.
+ */
 # define GCAL_TODO(_msg)                                                 \
    g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " TODO: %s():%d: %s",       \
          G_STRFUNC, __LINE__, _msg)
+
+/**
+ * GCAL_ENTRY:
+ *
+ * Prints an entry message. This shouldn't be used in
+ * critical functions. Place this at the beggining of
+ * the function, before any assertion.
+ */
 # define GCAL_ENTRY                                                      \
    g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, "ENTRY: %s():%d",           \
          G_STRFUNC, __LINE__)
+
+/**
+ * GCAL_EXIT:
+ *
+ * Prints an exit message. This shouldn't be used in
+ * critical functions. Place this at the end of
+ * the function, after any relevant code. If the
+ * function returns something, use GCAL_RETURN()
+ * instead.
+ */
 # define GCAL_EXIT                                                       \
    G_STMT_START {                                                        \
       g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " EXIT: %s():%d",        \
             G_STRFUNC, __LINE__);                                        \
       return;                                                            \
    } G_STMT_END
+
+/**
+ * GCAL_GOTO:
+ * @_l: goto tag
+ *
+ * Logs a goto jump.
+ */
 # define GCAL_GOTO(_l)                                                   \
    G_STMT_START {                                                        \
       g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " GOTO: %s():%d ("#_l")",\
             G_STRFUNC, __LINE__);                                        \
       goto _l;                                                           \
    } G_STMT_END
+
+/**
+ * GCAL_RETURN:
+ * @_r: the return value.
+ *
+ * Prints an exit message, and returns @_r. See #GCAL_EXIT.
+ */
 # define GCAL_RETURN(_r)                                                 \
    G_STMT_START {                                                        \
       g_log(G_LOG_DOMAIN, GCAL_LOG_LEVEL_TRACE, " EXIT: %s():%d ",       \
             G_STRFUNC, __LINE__);                                        \
       return _r;                                                         \
    } G_STMT_END
+
 #else
+
+/**
+ * GCAL_TODO:
+ * @_msg: the message to print
+ *
+ * Prints a TODO message.
+ */
 # define GCAL_TODO(_msg)
+
+/**
+ * GCAL_PROBE:
+ *
+ * Prints a probing message.
+ */
 # define GCAL_PROBE
+
+/**
+ * GCAL_TRACE_MSG:
+ * @fmt: printf-like format of the message
+ * @...: arguments for @fmt
+ *
+ * Prints a trace message.
+ */
 # define GCAL_TRACE_MSG(fmt, ...)
+
+/**
+ * GCAL_ENTRY:
+ *
+ * Prints a probing message. This shouldn't be used in
+ * critical functions. Place this at the beggining of
+ * the function, before any assertion.
+ */
 # define GCAL_ENTRY
+
+/**
+ * GCAL_GOTO:
+ * @_l: goto tag
+ *
+ * Logs a goto jump.
+ */
 # define GCAL_GOTO(_l)   goto _l
+
+/**
+ * GCAL_EXIT:
+ *
+ * Prints an exit message. This shouldn't be used in
+ * critical functions. Place this at the end of
+ * the function, after any relevant code. If the
+ * function returns somethin, use GCAL_RETURN()
+ * instead.
+ */
 # define GCAL_EXIT       return
+
+/**
+ * GCAL_RETURN:
+ * @_r: the return value.
+ *
+ * Prints an exit message, and returns @_r. See #GCAL_EXIT.
+ */
 # define GCAL_RETURN(_r) return _r
 #endif
 
+/**
+ * _GCAL_BUG: (skip)
+ */
 #define _GCAL_BUG(Component, Description, File, Line, Func, ...)                        \
   G_STMT_START {                                                                        \
     g_printerr ("-----------------------------------------------------------------\n"); \
@@ -91,6 +215,15 @@ G_BEGIN_DECLS
     g_printerr (Description"\n", ##__VA_ARGS__);                                        \
     g_printerr ("-----------------------------------------------------------------\n"); \
   } G_STMT_END
+
+/**
+ * GCAL_BUG:
+ * @Component: the component
+ * @Description: the description
+ * @...: extra arguments
+ *
+ * Logs a bug-friendly message.
+ */
 #define GCAL_BUG(Component, Description, ...) \
   _GCAL_BUG(Component, Description, __FILE__, __LINE__, G_STRFUNC, ##__VA_ARGS__)