There are no special comment symbols for Natural Docs.  You make a regular comment a Natural Docs comment by starting it with a "keyword: title" line.  You can use block comments or consecutive line comments.  The only requirement is that no part of the comment is on the same line as code.

/* Function: Multiply
   Multiplies two integers and returns the result. */

// Function: Multiply
// Multiplies two integers and returns the result.

Note that when using line comments, blank lines that you want to include in the documentation must start with the comment symbol as well.  If a line is completely blank that ends the comment and anything that follows won't be included.

If you have full language support you can use Javadoc-style comments to write Natural Docs documentation without a "keyword: title" line.  To do this you repeat the last symbol on the first line of the comment once, such as /**.  The comment must appear directly above a code element and it cannot contain any Javadoc tags like @param.

/**
 * Multiplies two integers and returns the result.
 */

///
// Multiplies two integers together and returns the result.

If there are any Javadoc tags the entire comment will be treated as Javadoc and can only use Javadoc formatting.  Otherwise it's treated as a Natural Docs comment and you can use all of its formatting options.  You can have both styles in the same source file but not in the same comment.

All comments do not have to be associated with code elements.  You can put standalone comments anywhere.  They follow the same scope rules as other comments, so if you put them under a Class comment they will be considered part of it.

/* About: License
 * This file is licensed under the GPL.
 */

You can also document more than one thing in a single comment.  Simply skip a line and include another "keyword: title" line.

/* About: License
 * This file is licensed under the GPL.
 *
 * About: Thread Safety
 * This class is not designed to be thread safe.
 */

If you use a plural keyword you create what's called a list comment.  Any items in definition lists will become linkable as if you wrote a separate comment for each one.  This allows you to document lists of small things quickly.

/* Constants: Counter Modes

   COUNTER_NORMAL - Causes the counter to increment normally.
   COUNTER_ODD    - Causes the counter to only increment in odd numbers.
   COUNTER_EVEN   - Causes the counter to only increment in even numbers.
*/
const int COUNTER_NORMAL = 0;
const int COUNTER_ODD = 1;
const int COUNTER_EVEN = 2;

You would now be able to write <COUNTER_ODD> and the link will work as if it had its own comment.

The enum and enumeration keywords are special because the enum will be documented as a type and any definition list items will be automatically documented as constants.  This allows both the enum and its values to be documented in the same place.

/* Enum: CounterMode

   Normal - Causes the counter to increment normally.
   Odd    - Causes the counter to only increment in odd numbers.
   Even   - Causes the counter to only increment in even numbers.
*/
enum CounterMode { Normal, Odd, Even };

How you link to the value (<Odd> vs. <CounterMode.Odd>) depends on the language and is controlled by the Enum Values property in Languages.txt.

When documenting a code element, Natural Docs comments should be placed directly above it.

// Function: Multiply
// Multiplies two integers and returns the result.
int Multiply (int x, int y)
    {  return x * y;  }

Doing this allows Natural Docs to detect prototypes for languages with basic support.  Prototypes are the gray boxes seen below.

For classes, this also allows Natural Docs to detect and display their parents and children for some languages with basic support.

Languages with full support are more forgiving.  The class hierarchy will be detected either way and you can put standalone comments in between the code's comment and declaration.

/* Class: Counter

      A class to handle a simple counter.

   About: Thread Safety

      This class is not designed to be thread safe.
*/
public class Counter
   { ... }

However, it's still recommended that you put them directly above the code element whenever possible for consistency.

Headerless comments must always be placed directly above its code element without exception.  Otherwise Natural Docs would have no way to tell what it's for.

Natural Docs will detect and ignore comment boxes and horizontal lines.  It doesn't matter what symbols they use.  The boxes don't need to be closed on the right side, and they can have different symbols for the edges and corners.

/* Function: Multiply
 * ------------------
 * Multiplies two integers and returns the result.
 */

/* +-------------------------------------------------+
   | Function: Multiply                              |
   | Multiplies two integers and returns the result. |
   +-------------------------------------------------+ */

//////////////////////////////////////////////////////////////
//
//  Function: Multiply
//  __________________
//
//  Multiplies two integers together and returns the result.
//
//////////////////////////////////////////////////////////////

Documentation can also be included in text files.  Any file with a .txt extension appearing in a source folder and starting with a "keyword: title" line will included in the documentation.  It's contents will be treated the same as the contents of a comment, meaning you can use all of Natural Docs' formatting, you can include multiple things by using multiple "keyword: title" lines, and you can have links between it and comments appearing in the code.

Remember that the "keyword: title" line is required to be the first line of content.  If the first non-blank line is not in that format the entire file will be ignored.  An easy way to do this is to use the Title keyword, although all of the other ones will work as well.

Title: License

This project is licensed under the GPL.

This method is convenient for documenting file formats, configuration settings, program architecture, or anything else that isn't directly tied to a source file.

Natural Docs will read and incorporate Javadoc and Microsoft XML comments that appear in languages with full support.  Natural Docs does not have perfect compatibility with these systems so while most content should work, some advanced features may not.

• Javadoc compatibility details

• Microsoft XML compatibility details

This is how Natural Docs determines how to interpret each comment:

• If the comment starts with a "keyword: title" line, it's always a Natural Docs comment.

• If the comment uses Javadoc comment symbols AND contains a Javadoc tag like @param, it's a Javadoc comment.

• If the comment uses XML or Javadoc comment symbols (Microsoft allows them to use either) AND the comment starts with an XML tag like <remark>, it's an XML comment.

• Otherwise, if the comment uses XML or Javadoc comment symbols and appears over a code element, it's a headerless Natural Docs comment.

If none of the above apply, the comment is ignored.

Perl users can use POD to do block comments.

=begin nd

Function: Multiply
Multiplies two integers and returns the result.

=cut

You can also use NaturalDocs or Natural Docs instead of ND, and it is not case sensitive.  If for some reason you want to go back to POD documentation instead of using =cut, you can write =end nd.

There's a second form of just =nd which is offered as a convenience.  However, it is not valid POD.  Perl will skip over it and execute fine, but POD parsers will give errors and possibly include the unformatted text in the output.  Use the longer, valid form unless you know for certain that no one will try to run POD on your code.