GNU Info

(standards.info)Doc Strings and Manuals

---

Next: Manual Structure Details Prev: GNU Manuals Up: Documentation

---

Enter node , (file) or (file)node

Doc Strings and Manuals
=======================

   Some programming systems, such as Emacs, provide a documentation
string for each function, command or variable.  You may be tempted to
write a reference manual by compiling the documentation strings and
writing a little additional text to go around them--but you must not do
it.  That approach is a fundamental mistake.  The text of well-written
documentation strings will be entirely wrong for a manual.

   A documentation string needs to stand alone--when it appears on the
screen, there will be no other text to introduce or explain it.
Meanwhile, it can be rather informal in style.

   The text describing a function or variable in a manual must not stand
alone; it appears in the context of a section or subsection.  Other text
at the beginning of the section should explain some of the concepts, and
should often make some general points that apply to several functions or
variables.  The previous descriptions of functions and variables in the
section will also have given information about the topic.  A description
written to stand alone would repeat some of that information; this
redundance looks bad.  Meanwhile, the informality that is acceptable in
a documentation string is totally unacceptable in a manual.

   The only good way to use documentation strings in writing a good
manual is to use them as a source of information for writing good text.