fx_module_doc Struct Reference

Documentation for an fx_module, used triply to provide usage information, to check input variables for correctness, and to enforce that programmers indeed do document their parameters. More...

Collaboration diagram for fx_module_doc:

[legend]

List of all members.

Public Attributes
struct fx_entry_doc *	entries
	All entries (params, timers, results) used by the module.
struct fx_submodule_doc *	submodules
	All submodules used by the module.
const char *	text
	Information to print on --help.

Detailed Description

Documentation for an fx_module, used triply to provide usage information, to check input variables for correctness, and to enforce that programmers indeed do document their parameters.

In addition to lists of fx_entry_docs and fx_submodule_docs, you should define a constant of type fx_module_doc at the top of any file/class that makes use of an fx_module. This constant is then used with either fx_init or other fx_submodule_docs.

Example (a hypothetical manifold method):

   const fx_entry_doc manifold_entries[] = {
     {"maxiter", FX_PARAM, FX_INT, NULL,
      "  Maximum number of refinement iterations (def 50).\n"},

     {"thresh", FX_REQUIRED, FX_DOUBLE, NULL,
      "  Threshold parameter of the algorithm.\n"
      "  Smaller is more accurate but slower.\n"},

     {"emit_iter_times", FX_PARAM, FX_BOOL, NULL,
      "  Whether to emit running times for each iteration.\n"}

     {"time_i", FX_TIMER, FX_DOUBLE, NULL,
      "  The running time of iteration i.\n"},

     {"total_time", FX_TIMER, FX_DOUBLE, NULL,
      "  The running time of all iterations.\n"},

     {"sq_error", FX_RESULT, FX_DOUBLE, NULL,
      "  The squared error of the final result.\n"},

     {"knn_i/k", FX_RESERVED, FX_INT, NULL,
      "  Reserved (selected by algorithm).\n"},

     FX_ENTRY_DOC_DONE
   };

  const fx_submodule_doc manifold_submodules[] = {
    {"knn_i", &knn_doc,
     "  The k-nearest-neighbors step used in each iteration.\n"},

    FX_SUBMODULE_DOC_DONE
  };

  const fx_moduld_doc manifold_doc = {
    manifold_entries, manifold_submodules,
    "An implementation of a hypothetical manifold method.\n"
  };

In the above, note that "knn_i/k" is a reserved parameter. This fx_entry_doc will path into the knn_i submodule and override its documented type (normally an FX_PARAM). The manifold module is then free to assume that "knn_i/k" has not been set on the command line, which would be mistaken because the algorithm sets this parameter itself.

Also observe documentation for timer "time_i". This is not literally the name of the timer entries that will be emitted, but instead serves as a stub to be copied into new entries "time_1", "time_2", and so forth. The same copying will occur for the knn_i submodule for each iteration.

The above is incomplete, however. It is the documentation for the manifold module, but not the documentation for the entire program. In the same file that defines main, there should be an additional fx_module_doc that references manifold_doc as well as parameters listing which files to open, etc. This documentation would include &manifold_doc as one of its submodules.