Ticket #21 (closed enhancement: fixed)

Opened 6 years ago

Last modified 6 years ago

Modules should be self documenting.

Reported by: jesus Assigned to: jesus
Priority: major Milestone: Ploy
Component: noitd Severity:
Keywords: Cc:

Description

I have to go read source to figure out what the configuration parameters are. This should be documented in the code in a fashion that it can be:

  • extracted for stand-alone documentation
  • exposed by via the console for "online help"

Change History

06/03/08 17:17:04 changed by jesus

  • status changed from new to assigned.

I've considered DTDs and RelaxNG for this, but as the config is inherited, there is no good what to use with for validation -- which eliminates much of their purpose. I think some simple documentation like:

  • keyname
  • allowed values
  • description
  • required/optional/dependent/etc.

08/27/08 13:17:50 changed by jesus

<module>
  <name>Terse Name</name>
  <description>Longer purpose statement</description>
  <loader>C/lua</loader>
  <image>module.so</image>
  <object>lua.module.name</object>
  <moduleconfig>
    <parameter name="regex" required="true" allowed="regex">Description</parameter>
    <parameter ... />
  </moduleconfig>
  <checkconfig>
    <parameter name="regex" required="true" allowed="regex">Description</parameter>
    <parameter ... />
  </checkconfig>
  <examples>
    <example>....</example>
    <example>....</example>
  </examples>
</module>

08/29/08 03:29:11 changed by jesus

forgot to ref this ticket from [399]

09/06/08 23:51:20 changed by jesus

(In [416]) pull help and docs into the console, refs #21

09/07/08 00:45:41 changed by jesus

  • status changed from assigned to closed.
  • resolution set to fixed.

I think the premise is done here. The rest should be a new exercise.

09/07/08 01:28:24 changed by jesus

(In [417]) ignore and some varnish docs, refs #21

09/07/08 05:17:34 changed by jesus

(In [419]) more docs, fixups.. Better smtp options and docs. refs #21

09/07/08 15:38:27 changed by jesus

(In [420]) autobuild docs form lua stuff... the things you can do in lua are as evil as perl, refs #21

09/07/08 21:38:47 changed by jesus

(In [422]) oops, extract_xml.lua produces just the meta XML, need to docbook it, refs #21

09/08/08 04:14:11 changed by jesus

(In [425]) integrate command line docs as usage, refs #21

09/08/08 15:54:07 changed by jesus

(In [427]) integrate command line docs as usage, refs #21