From c0e08a14cb5681faac6bd4b2567fe153f2421273 Mon Sep 17 00:00:00 2001
From: Jan 'Moskyt' Matejka <mq@ucw.cz>
Date: Mon, 22 Apr 2013 17:08:38 +0200
Subject: [PATCH] Opt: docs fixes

---
 ucw/doc/Makefile  |  2 +-
 ucw/doc/index.txt |  1 +
 ucw/opt.h         | 42 +++++++++++++++++++++++++-----------------
 3 files changed, 27 insertions(+), 18 deletions(-)

diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile
index 7a018f3d..962f168d 100644
--- a/ucw/doc/Makefile
+++ b/ucw/doc/Makefile
@@ -2,7 +2,7 @@
 
 DIRS+=ucw/doc
 
-UCW_DOCS=basics log fastbuf index config configure install basecode hash docsys conf mempool eltpool mainloop generic growbuf unaligned lists chartype unicode prime binsearch heap binheap compress sort hashtable relnotes trans string time daemon signal varint
+UCW_DOCS=basics log fastbuf index config configure install basecode hash docsys conf mempool eltpool mainloop generic growbuf unaligned lists chartype unicode prime binsearch heap binheap compress sort hashtable relnotes trans string time daemon signal varint opt
 UCW_INDEX=$(o)/ucw/doc/def_index.html
 UCW_DOCS_HTML=$(addprefix $(o)/ucw/doc/,$(addsuffix .html,$(UCW_DOCS)))
 
diff --git a/ucw/doc/index.txt b/ucw/doc/index.txt
index f8240068..33002353 100644
--- a/ucw/doc/index.txt
+++ b/ucw/doc/index.txt
@@ -43,6 +43,7 @@ Modules
 - <<time:,Time and timers>>
 - <<daemon:,Daemon helpers>>
 - <<signal:,Signal helpers>>
+- <<opt:,Command line parser>>
 
 Other features
 --------------
diff --git a/ucw/opt.h b/ucw/opt.h
index 00a98ce9..368a9801 100644
--- a/ucw/opt.h
+++ b/ucw/opt.h
@@ -18,8 +18,6 @@
 
 /***
  * [[opt]]
- * Parsing of command line options
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  ***/
 
 enum opt_class {
@@ -60,7 +58,9 @@ struct opt_section {
 
 #define OPT_ITEMS	.opt = ( struct opt_item[] )  /** List of sub-items. **/
 
-/** Sub-items to be enclosed in OPT_ITEMS { } list
+/***
+ * Sub-items to be enclosed in OPT_ITEMS { } list
+ * ----------------------------------------------
  *
  * OPT_SHOW_HELP declares --help and prints a line about that
  * OPT_HELP prints a line into help()
@@ -76,7 +76,7 @@ struct opt_section {
  * OPT_INC declares an incremental value like -v/--verbose
  * OPT_SECTION declares a subsection
  *
- * **/
+ ***/
 
 #define OPT_SHOW_HELP OPT_CALL(0, "help", opt_show_help_internal, OPT_NO_VALUE, "Show this help")
 #define OPT_HELP(line) OPT_HELP2(line, NULL)
@@ -92,22 +92,30 @@ struct opt_section {
 #define OPT_SECTION(sec) { .cls = OPT_CL_SECTION, .u.section = &sec }
 #define OPT_END { .cls = OPT_CL_END }
 
-/** Flags for the preceeding calls **/
-#define OPT_REQUIRED	    0x1		// Argument must appear at the command line
-#define OPT_REQUIRED_VALUE  0x2		// Argument must have a value
-#define OPT_NO_VALUE	    0x4		// Argument must have no value
-#define OPT_MAYBE_VALUE	    0x8		// Argument may have a value
+/***
+ * Flags for the preceeding calls
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ ***/
+
+#define OPT_REQUIRED	    0x1		/** Argument must appear at the command line **/
+#define OPT_REQUIRED_VALUE  0x2		/** Argument must have a value **/
+#define OPT_NO_VALUE	    0x4		/** Argument must have no value **/
+#define OPT_MAYBE_VALUE	    0x8		/** Argument may have a value **/
 #define OPT_VALUE_FLAGS	    (OPT_REQUIRED_VALUE | OPT_NO_VALUE | OPT_MAYBE_VALUE)
-#define OPT_DECREMENT	    0x10	// Reversing the effect of OPT_INC
-#define OPT_SINGLE	    0x20	// Argument must appear at most once
-#define OPT_NO_HELP	    0x40	// Omit this line from help
+#define OPT_DECREMENT	    0x10	/** Reversing the effect of OPT_INC **/
+#define OPT_SINGLE	    0x20	/** Argument must appear at most once **/
+#define OPT_NO_HELP	    0x40	/** Omit this line from help **/
 
-/** Value flags defaults:
+/***
+ * Value flags defaults
+ * ~~~~~~~~~~~~~~~~~~~~
+ *
  * OPT_NO_VALUE for OPT_BOOL, OPT_SWITCH and OPT_INC
  * OPT_MAYBE_VALUE for OPT_STRING, OPT_UNS, OPT_INT
  * Some of the value flags (OPT_NO_VALUE, OPT_MAYBE_VALUE, OPT_REQUIRED_VALUE)
  * must be specified for OPT_CALL and OPT_USER.
- */
+ ***/
+
 static uns opt_default_value_flags[] = {
   [OPT_CL_BOOL] = OPT_NO_VALUE,
   [OPT_CL_STATIC] = OPT_MAYBE_VALUE,
@@ -147,13 +155,13 @@ static void opt_usage(void) {
 
 /**
  * Init the opt engine.
- */
+ **/
 void opt_init(struct opt_section * options);
 
 /**
  * Parse all the arguments.
  * Returns the number of positional arguments and an array of them in @posargs.
- */
+ **/
 int opt_parse(char ** argv, char *** posargs);
 
 /**
@@ -161,7 +169,7 @@ int opt_parse(char ** argv, char *** posargs);
  * Returns the position of that argument in argv.
  * On next call of this function, start from the next item in argv.
  * Iterate this function to get all the positional arguments.
- */
+ **/
 int opt_get(char ** argv);
 
 #endif
-- 
2.39.2