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