[DOC] Improve reference documentation for babel.c

[andy/viking.git] / src / babel.h

diff --git a/src/babel.h b/src/babel.h
index 967eb5376f5112317c88f13d9767c52030790701..e60aeb55767352774297e7dacc494b439393af86 100644 (file)
--- a/src/babel.h
+++ b/src/babel.h
@@ -27,47 +27,30 @@
 
 #include "viktrwlayer.h"
 
+/**
+ * BabelProgressCode:
+ * @BABEL_DIAG_OUTPUT: a line of diagnostic output is available. The pointer is to a 
+ *                     NULL-terminated line of diagnostic output from gpsbabel.
+ * @BABEL_DONE: gpsbabel finished, or %NULL if no callback is needed.
+ *
+ * Used when calling #BabelStatusFunc.
+ */
 typedef enum {
   BABEL_DIAG_OUTPUT,
   BABEL_DONE,
 } BabelProgressCode;
 
+/**
+ * BabelStatusFunc:
+ *
+ * Callback function.
+ */
 typedef void (*BabelStatusFunc)(BabelProgressCode, gpointer, gpointer);
 
-/*
- * a_babel_convert modifies data in a trw layer using gpsbabel filters.  This routine is synchronous;
- * that is, it will block the calling program until the conversion is done.  To avoid blocking, call
- * this routine from a worker thread.  The arguments are as follows:
- * 
- * vt              The TRW layer to modify.  All data will be deleted, and replaced by what gpsbabel outputs.
- * 
- * babelargs       A string containing gpsbabel command line filter options.  No file types or names should
- *                 be specified.
- * 
- * cb             A callback function, called with the following status codes:
- *                   BABEL_DIAG_OUTPUT: a line of diagnostic output is available.  The pointer is to a 
- *                                      NUL-terminated line of diagnostic output from gpsbabel.
- *                   BABEL_DIAG_DONE: gpsbabel finished,
- *                 or NULL if no callback is needed.
- */
 gboolean a_babel_convert( VikTrwLayer *vt, const char *babelargs, BabelStatusFunc cb, gpointer user_data );
-
-/*
- * a_babel_convert_from loads data into a trw layer from a file, using gpsbabel.  This routine is synchronous;
- * that is, it will block the calling program until the conversion is done.  To avoid blocking, call
- * this routine from a worker thread. The arguments are as follows:
- * 
- * vt              The TRW layer to place data into.  Duplicate items will be overwritten. 
- * 
- * babelargs       A string containing gpsbabel command line options.  In addition to any filters, this string
- *                 must include the input file type (-i) option. 
- * 
- * cb             Optional callback function. Same usage as in a_babel_convert.
- */
 gboolean a_babel_convert_from( VikTrwLayer *vt, const char *babelargs, BabelStatusFunc cb, const char *file, gpointer user_data );
 gboolean a_babel_convert_from_shellcommand ( VikTrwLayer *vt, const char *input_cmd, const char *input_file_type, BabelStatusFunc cb, gpointer user_data );
 gboolean a_babel_convert_from_url ( VikTrwLayer *vt, const char *url, const char *input_type, BabelStatusFunc cb, gpointer user_data );
 gboolean a_babel_convert_to( VikTrwLayer *vt, const char *babelargs, BabelStatusFunc cb, const char *file, gpointer user_data );
 
-
 #endif