standards: Doc Strings and Manuals

1 
1 6.2 Doc Strings and Manuals
1 ===========================
1 
1 Some programming systems, such as Emacs, provide a documentation string
1 for each function, command or variable.  You may be tempted to write a
1 reference manual by compiling the documentation strings and writing a
1 little additional text to go around them--but you must not do it.  That
1 approach is a fundamental mistake.  The text of well-written
1 documentation strings will be entirely wrong for a manual.
1 
1    A documentation string needs to stand alone--when it appears on the
1 screen, there will be no other text to introduce or explain it.
1 Meanwhile, it can be rather informal in style.
1 
1    The text describing a function or variable in a manual must not stand
1 alone; it appears in the context of a section or subsection.  Other text
1 at the beginning of the section should explain some of the concepts, and
1 should often make some general points that apply to several functions or
1 variables.  The previous descriptions of functions and variables in the
1 section will also have given information about the topic.  A description
1 written to stand alone would repeat some of that information; this
1 redundancy looks bad.  Meanwhile, the informality that is acceptable in
1 a documentation string is totally unacceptable in a manual.
1 
1    The only good way to use documentation strings in writing a good
1 manual is to use them as a source of information for writing good text.
1