Revision: 65285
http://sourceforge.net/p/brlcad/code/65285
Author: starseeker
Date: 2015-06-12 20:46:53 +0000 (Fri, 12 Jun 2015)
Log Message:
-----------
Start working on doxygen markup for bu_opt
Modified Paths:
--------------
brlcad/trunk/include/bu/opt.h
brlcad/trunk/misc/doxygen/libbu.dox
Modified: brlcad/trunk/include/bu/opt.h
===================================================================
--- brlcad/trunk/include/bu/opt.h 2015-06-12 20:05:42 UTC (rev 65284)
+++ brlcad/trunk/include/bu/opt.h 2015-06-12 20:46:53 UTC (rev 65285)
@@ -32,26 +32,7 @@
* @brief
* Generalized option handling.
*
- */
-/** @{ */
-/** @file bu/opt.h */
-
-/**
- * Callback function signature for bu_opt_desc argument processing functions.
- *
- * Return values:
- *
- * -1 - Invalid argument encountered.
- * 0 - No argument processed.
- * >0 - Number of argv elements used in valid argument processing.
- *
- */
-typedef int (*bu_opt_arg_process_t)(struct bu_vls *, int argc, const char
**argv, void *);
-
-/**
- * "Option description" structure.
- *
- * This structure is used to define a command line option. The usage pattern
is to
+ * The usage pattern is to
* build up a BU_OPT_DESC_NULL terminated array of option descriptions, which
are
* used by bu_opt_parse to process an argv array.
*
@@ -59,7 +40,8 @@
* needed is determined by the arg_process callback. If no callback is
present and
* the max arg count is zero, set_var is expected to be an integer that will
be set
* to 1 if the option is present in the argv string.
-*
+
+ *
* @code
* #define help_str "Print help and exit"
* static int ph = 0;
@@ -80,23 +62,6 @@
* variables rendering the function in question thread unsafe. For an approach
* usable in a library see the BU_OPT macro documentation.
*
- */
-struct bu_opt_desc {
- const char *shortopt;
- const char *longopt;
- const char *arg_helpstr;
- bu_opt_arg_process_t arg_process;
- void *set_var;
- const char *help_string;
-};
-
-/* Convenience definition for NULL bu_opt_desc struct */
-#define BU_OPT_DESC_NULL {NULL, NULL, NULL, NULL, NULL, NULL}
-
-/**
- * Macro for assigning values to bu_opt_desc array entries. Use this style
- * when it isn't possible to use static variables as set_var entries
- * (such as libraries which need to be thread safe.)
*
* @code
* #define help_str "Print help and exit"
@@ -108,8 +73,51 @@
* BU_OPT(opt_defs[1], "n", "num", &bu_opt_ind, (void *)&i, "#",
"Read int");
* BU_OPT(opt_defs[2], "f", "fastf_t", &bu_opt_fastf_t, (void *)&f, "#",
"Read float");
* BU_OPT_NULL(opt_defs[3]);
+ * @endcode
*
*/
+/** @{ */
+/** @file bu/opt.h */
+
+/**
+ * Callback function signature for bu_opt_desc argument processing functions.
Any
+ * user defined argument processing function should match this signature and
return
+ * values as documented below.
+ *
+ * \returns
+ * Val | Interpretation
+ * --- | --------------
+ * -1 | Invalid argument encountered, or argument expected but not found.
+ * 0 | No argument processed (not an error.)
+ * >0 | Number of argv elements used in valid argument processing.
+ *
+ */
+typedef int (*bu_opt_arg_process_t)(struct bu_vls *, int argc, const char
**argv, void *);
+
+/**
+ * @brief
+ * "Option description" structure.
+ *
+ * Arrays of this structure are used to define command line options.
+ *
+ */
+struct bu_opt_desc {
+ const char *shortopt; /**< @brief "Short" option (i.e. -h for
help option) */
+ const char *longopt; /**< @brief "Long" option (i.e. --help
for help option) */
+ const char *arg_helpstr; /**< @brief Documentation describing
option argument, if any (i.e. "file" in --input file)*/
+ bu_opt_arg_process_t arg_process; /**< @brief Argument processing function
pointer */
+ void *set_var; /**< @brief Pointer to the variable or
structure that collects this option's results */
+ const char *help_string; /**< @brief Option description */
+};
+
+/** Convenience initializer for NULL bu_opt_desc array terminator */
+#define BU_OPT_DESC_NULL {NULL, NULL, NULL, NULL, NULL, NULL}
+
+/**
+ * Macro for assigning values to bu_opt_desc array entries. Use this style
+ * when it isn't possible to use static variables as set_var entries
+ * (such as libraries which need to be thread safe.)
+ */
#define BU_OPT(_desc, _so, _lo, _ahelp, _aprocess, _var, _help) { \
_desc.shortopt = _so; \
_desc.longopt = _lo; \
@@ -134,13 +142,13 @@
*
* The bu_opt_desc array ds must be null terminated with BU_OPT_DESC_NULL.
*
- * Return vals:
+ * \returns
+ * Val | Interpretation
+ * --- | --------------
+ * -1 | fatal error in parsing. Program must decide to recover or exit.
+ * 0 | all argv options handled.
+ * >0 | number of unused argv entries returned at the begging of the argv
array.
*
- * -1 - fatal error in parsing. Program must decide to recover or exit.
- * 0 - all argv options handled.
- * >0 - some unused argv entries returned at the beginning of the argv array.
- * returned int is unused argc count.
- *
* msgs will collect any informational messages generated by the parser
(typically
* used for error reporting.)
*
@@ -152,7 +160,9 @@
BU_EXPORT extern int bu_opt_parse(struct bu_vls *msgs, int ac, const char
**argv, struct bu_opt_desc *ds);
-/* Standard option validators - if a custom option argument
+/** @addtogroup bu_opt_arg_process
+ *
+ * Standard option validators - if a custom option argument
* validation isn't needed, the functions below can be
* used for most valid data types. When data conversion is successful,
* the user_data pointer in bu_opt_data will point to the results
@@ -160,12 +170,14 @@
* program to use the int/long/etc. without having to repeat the
* conversion.
*/
+/** @{ */
BU_EXPORT extern int bu_opt_bool(struct bu_vls *msg, int argc, const char
**argv, void *set_var);
BU_EXPORT extern int bu_opt_int(struct bu_vls *msg, int argc, const char
**argv, void *set_var);
BU_EXPORT extern int bu_opt_long(struct bu_vls *msg, int argc, const char
**argv, void *set_var);
BU_EXPORT extern int bu_opt_fastf_t(struct bu_vls *msg, int argc, const char
**argv, void *set_var);
BU_EXPORT extern int bu_opt_str(struct bu_vls *msg, int argc, const char
**argv, void *set_var);
BU_EXPORT extern int bu_opt_vls(struct bu_vls *msg, int argc, const char
**argv, void *set_var);
+/** @} */
/** Output format options for bu_opt documentation generation */
Modified: brlcad/trunk/misc/doxygen/libbu.dox
===================================================================
--- brlcad/trunk/misc/doxygen/libbu.dox 2015-06-12 20:05:42 UTC (rev 65284)
+++ brlcad/trunk/misc/doxygen/libbu.dox 2015-06-12 20:46:53 UTC (rev 65285)
@@ -91,8 +91,12 @@
/** @ingroup bu_data */
/** @defgroup bu_conv Data Conversion */
/** @ingroup bu_data */
-/** @defgroup bu_getopt Command-line Option Parsing*/
+/** @defgroup bu_getopt Basic Command-line Option Parsing*/
/** @ingroup bu_data */
+/** @defgroup bu_opt Generalized Command-line Option Parsing*/
+/** @ingroup bu_opt */
+/** @defgroup bu_opt_arg_process Pre-Defined Option Parsers*/
+/** @ingroup bu_data */
/** @defgroup bu_hist Histogram Handling */
/** @ingroup bu_data */
/** @defgroup bu_sort Sorting Algorithms */
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
_______________________________________________
BRL-CAD Source Commits mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/brlcad-commits
