ucw docs: Some more in conf system

Documented something about loading the configuration by functions in
ucw/getopt.h.

diff --git a/ucw/doc/conf.txt b/ucw/doc/conf.txt
index 85b6b798d7d8bd15c902d707923fea5dcc3ca0a3..6c46a7a43c3a5dd31a8481a1d37168445e2a2632 100644 (file)
--- a/ucw/doc/conf.txt
+++ b/ucw/doc/conf.txt
@@ -26,6 +26,12 @@ from command line.
   * <<alloc,Memory allocation>>
   * <<journal,Undo journal>>
   * <<bparser,Parsers for basic types>>
+- <<getopt_h,ucw/getopt.h>>
+  * <<conf_load,Safe configuration loading>>
+  * <<conf_direct,Direct access>>
+  * <<conf_dump,Debug dumping>>
+  * <<conf_journal,Journaling control>>
+  * <<conf_getopt,Loading by cf_getopt()>>
 
 [[example]]
 Example
@@ -119,3 +125,12 @@ Use this file if you want define a configuration section, request
 loading of some variables or create new item type.
 
 !!ucw/conf.h
+
+[[getopt_h]]
+ucw/getopt.h
+------------
+
+This header contains routines for parsing command line arguments and
+loading the configuration.
+
+!!ucw/getopt.h

diff --git a/ucw/getopt.h b/ucw/getopt.h
index 531d2582e2607063df98e3b426fa4886fc37c53b..2c6da5fb8cbb6dee8f4c7fc8406f98b4a958530e 100644 (file)
--- a/ucw/getopt.h
+++ b/ucw/getopt.h
@@ -17,17 +17,38 @@
 #include <getopt.h>
 #endif
 
-void reset_getopt(void);
+void reset_getopt(void);       /** If you want to start parsing of the arguments from the first one again. **/
 
-/* Safe loading and reloading of configuration files: conf-input.c */
+/***
+ * [[conf_load]]
+ * Safe configuration loading
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * These functions can be used to to safely load or reload configuration.
+ */
 
+/**
+ * The default config (DEFAULT_CONFIG config option) or NULL if already loaded.
+ * You can set it to something else manually.
+ */
 extern char *cf_def_file;              /* DEFAULT_CONFIG; NULL if already loaded */
 extern char *cf_env_file;              /* ENV_VAR_CONFIG */
-int cf_reload(const char *file);
-int cf_load(const char *file);
+int cf_reload(const char *file);       /** Reload configuration from @file, replace the old one. **/
+int cf_load(const char *file);         /** Load configuration from @file. **/
+/**
+ * Parse some part of configuration passed in @string.
+ * The syntax is the same as in the <<config:,configuration file>>.
+ **/
 int cf_set(const char *string);
 
-/* Direct access to configuration items: conf-intr.c */
+/***
+ * [[conf_direct]]
+ * Direct access
+ * ~~~~~~~~~~~~~
+ *
+ * Direct access to configuration items.
+ * You probably should not need this.
+ ***/
 
 #define CF_OPERATIONS T(CLOSE) T(SET) T(CLEAR) T(ALL) \
   T(APPEND) T(PREPEND) T(REMOVE) T(EDIT) T(AFTER) T(BEFORE) T(COPY)
@@ -41,39 +62,68 @@ enum cf_operation { CF_OPERATIONS };
 #undef T
 
 struct cf_item;
+/**
+ * Searches for a configuration item called @name.
+ * If it is found, it is copied into @item and NULL is returned.
+ * Otherwise, an error is returned and @item is zeroed.
+ **/
 char *cf_find_item(const char *name, struct cf_item *item);
+// TODO What does this do?
 char *cf_write_item(struct cf_item *item, enum cf_operation op, int number, char **pars);
 
-/* Debug dumping: conf-dump.c */
+/***
+ * [[conf_dump]]
+ * Debug dumping
+ * ~~~~~~~~~~~~~
+ ***/
 
 struct fastbuf;
+/**
+ * Take everything and write it into @fb.
+ **/
 void cf_dump_sections(struct fastbuf *fb);
 
-/* Journaling control: conf-journal.c */
+/***
+ * [[conf_journal]]
+ * Journaling control
+ * ~~~~~~~~~~~~~~~~~~
+ ***/
 
 struct cf_journal_item;
+// TODO
 struct cf_journal_item *cf_journal_new_transaction(uns new_pool);
 void cf_journal_commit_transaction(uns new_pool, struct cf_journal_item *oldj);
 void cf_journal_rollback_transaction(uns new_pool, struct cf_journal_item *oldj);
 
-/*
- * cf_getopt() takes care of parsing the command-line arguments, loading the
- * default configuration file (cf_def_file) and processing configuration options.
- * The calling convention is the same as with GNU getopt_long(), but you must prefix
- * your own short/long options by the CF_(SHORT|LONG)_OPTS or pass CF_NO_LONG_OPTS
- * of there are no long options.
- *
- * The default configuration file can be overriden by the --config options,
- * which must come first. During parsing of all other options, the configuration
- * is already available.
- */
+/***
+ * [[conf_getopt]]
+ * Loading by @cf_getopt()
+ * ~~~~~~~~~~~~~~~~~~~~~~~
+ ***/
 
+/**
+ * Short options for loading configuration by @cf_getopt().
+ * Prepend to your own options.
+ **/
 #define        CF_SHORT_OPTS   "C:S:"
+/**
+ * Long options for loading configuration by @cf_getopt().
+ * Prepend to your own options.
+ **/
 #define        CF_LONG_OPTS    {"config",      1, 0, 'C'}, {"set",             1, 0, 'S'}, CF_LONG_OPTS_DEBUG
+/**
+ * Use this constant as @long_opts parameter of @cf_getopt() if you do
+ * not have any long options in your program.
+ **/
 #define CF_NO_LONG_OPTS (const struct option []) { CF_LONG_OPTS { NULL, 0, 0, 0 } }
 #ifndef CF_USAGE_TAB
 #define CF_USAGE_TAB ""
 #endif
+/**
+ * This macro provides text describing usage of the configuration
+ * loading options. Concatenate with description of your options and
+ * write to the user, if he/she provides invalid options.
+ **/
 #define        CF_USAGE        \
 "-C, --config filename\t" CF_USAGE_TAB "Override the default configuration file\n\
 -S, --set sec.item=val\t" CF_USAGE_TAB "Manual setting of a configuration item\n" CF_USAGE_DEBUG
@@ -86,7 +136,18 @@ void cf_journal_rollback_transaction(uns new_pool, struct cf_journal_item *oldj)
 #define CF_USAGE_DEBUG
 #endif
 
-// conf-input.c
+/***
+ * Takes care of parsing the command-line arguments, loading the
+ * default configuration file (<<var_cf_def_file,`cf_def_file`>>) and processing
+ * configuration options. The calling convention is the same as with GNU getopt_long(),
+ * but you must prefix your own short/long options by the
+ * <<def_CF_LONG_OPTS,`CF_LONG_OPTS`>> or <<def_CF_SHORT_OPTS,`CF_SHORT_OPTS`>>or
+ * pass <<def_CF_NO_LONG_OPTS,`CF_NO_LONG_OPTS`>> if there are no long options.
+ *
+ * The default configuration file can be overwriten by the --config options,
+ * which must come first. During parsing of all other options, the configuration
+ * is already available.
+ ***/
 int cf_getopt(int argc, char * const argv[], const char *short_opts, const struct option *long_opts, int *long_index);
 
 #endif