About the Documentation

• Writing main documentation
• Commenting source code

• Editing
• Formatting for NaturalDocs
• CSS customization for NaturalDocs

All comments in Pascal intended for documentation should be of the parenthesis-astrisk form.  The opening line should contain the open parenthesis as well as the NaturalDocs keyword.  The closing parenthesis may go either at the end of the text if the comment is short, or on a line by itself, aligned with the open parenthesis, if the comment is long

(* Title: A Short Comment *)

or

(* Topic: A Longer Comment
      This comment could go on for days. It could constantly
      reference how long the comment is going on, and in a
      feedback loop continue on and on about how the comment
      just keeps going on. Fortunately that won't happen.
  *)

In some instances, Naturaldocs ignores blank space, in others, it uses it as markup.

In general, use blank lines to seperate things.  To seperate paragraphs, place an empty line in between them.  Headings are made by putting an empty line before some text ending in a colon “:”.

The first sentence for each topic is shown as the description for that entry wherever it appears.  Sometimes as a tooltip, sometimes in Summaries.  For these situations, use a definition style sentence.  So just write as if the sentence started with “Topic is..” ie

Property: Name
  The property for naming a component. This property contains a definition
  style sentence for the first sentence, and a full, compound sentence after
  that.

This reads like “Name is the property for naming a component.”  After that, using full sentences works fine.

Many people misuse hyphens to seperate a parenthetic (an extra phrase in the middle of a sentence, like this) because they are confusing them with dashes.  In plain text, a hyphen is “-” and a dash is represented by two hyphens in a row, such as “--”.

In this situation, parenthesis (parenthetic) or dashes -- parenthetic -- are correct.  Additionally, NaturalDocs won’t mangle these because it doesn’t use them for markup.

When forming the topic line for a function, use just the function name as the topic.  A prototype will appear in the generated documentation with the full interface declaration, so all parameters and returns will be visible.  The main reason for this is that when linking to a function where the return is specified in the topic, the return must be specified in the link as well.  Linking to <GetFilename: string> is a bit awkward.

When forming the topic line for a variable, again, use just the variable name as the topic.  This is for the same linking reason mentioned above.  However variables will not have a protoype attached to them, and therefore it may not be obvious in the HTML documentation what type of variable it is.  For this reason it is best to include the type in the topic sentence of the documentation for the variable.

(* Variable: FList
      A TStringList which holds some values. *)
FList: TStringList

Asterisks are common characters when dealing with computer related subject matter.  Fortunately most of the ways they are use will not be picked up by NaturalDocs.  There are however some instances where it will pick them up as markup for bold.

Naturaldocs looks for a space and then an asterisk to start bold text, then it looks for a closing asterisk to end it.  For this reason, sentences with, two wildcard references get picked up as having bold text.

This sentence mentions *.wav and *.mp3 files.

This sentence mentions *.wav and *.mp3 files.

To prevent this from happening, simply reference files by their extension without specifying the wildcard.  To reference MP3 and WAV files works just fine, and is arguably more correct.  In instances where wildcards simply must be dealt with, explain them in text, and give an example of them using code blocks.

Topic: Listing Files in DOS
    You can use wildcards with the DIR command. To list
    all files with the TXT extension, use the following.

    > dir *.txt