Comments.txt

Natural Docs has two files called Comments.txt: one in its Config folder, and one in your project configuration folder. These control the keywords and comment behavior.

You should edit the one in your project configuration folder whenever possible. It keeps your changes separate and easier to manage, plus you won't have to reapply them whenever you upgrade. Editing the one in Natural Docs' Config folder would be better only if you're using Natural Docs with a lot of projects and would like the changes to apply everywhere.

Comments.txt was known as Topics.txt in Natural Docs 1.x. If you run Natural Docs 2.0 with your old configuration files it will copy the settings to Comments.txt automatically.

Keywords vs. Comment Types

When you're writing a Natural Docs comment you're using a keyword. In "Function: MyFunction", Function is a keyword. However, you could also use Procedure, Method, or any of the other synonyms and abbreviations and it will work exactly the same. You can use whatever is most natural to you. This helps Natural Docs conform to how you write instead of the other way around.

All the keywords map to a comment type which sets behavior such as scope, prototype detection, and whether it appears in the class hierarchy. Comments.txt manages both keywords and comment types.

Adding Comment Types

If you want to be able to document something Natural Docs doesn't handle by default you can create a comment type for it. Let's say you're working on a video game and you want to document all the sound effects. You'd add this to Comments.txt in your project configuration folder:

    Comment Type: Sound Effect
       Plural: Sound Effects
       Keywords:
          sound
          sound effect

Sound effects can now be documented with the sound or sound effect keywords. The Plural line just specifies the plural name of the comment type. It isn't required, but Natural Docs will use it in some places where the plural would sound more natural, like when grouping things in the summary.

Here are a couple of other things you may want to add:

    Comment Type: Sound Effect
       Plural: Sound Effects
       Scope: Always Global
       Keywords:
          sound, sounds
          sound effect, sound effects

You can set the scope behavior of the comment type. Your options are:

Normal | Comments stay within the current scope.
Start | Comments start a new scope for all the comments beneath it, like class comments.
End | Comments reset the scope back to global for all the comments beneath it.
Always Global | Comments are defined as global, but do not change the scope for any other comments.

Here we set it to Always Global so that if we document one as part of a class, it will still be global yet will not break the class' scope. In other words, we can always link to it with just its name instead of needing something like <Class.Sound>.

The other thing we did was add plural keywords, which you do by using a comma after an existing keyword. These keywords are used for list comments so we don't have to document each one individually with the full syntax.

There are more options, these are just the most important ones. See the full syntax reference for the rest.

Prototypes

If your new comment type is for a code element and you'd like to include their prototypes in the documentation, you have to do that per language by editing Languages.txt.

Changing Keywords
Adding and Redefining

If you're creating your own comment type or editing the system Comments.txt file, you can simply add to the keywords list:

    Comment Type: Sound Effect
       Keywords:
          sound, sounds
          sound effect, sound effects

It doesn't matter if the keyword was previously defined for a different comment type. Just declare it again and the definition will change.

If you want to add keywords to one of the system types from your project configuration file, use Alter Comment Type instead:

    Alter Comment Type: Information
       Keywords:
          note
          notes

Removing

Sometimes a keyword just gets in the way. Maybe it's too common in your comments and Natural Docs keeps picking it up as documentation when that isn't what you wanted. You can get rid of keywords completely by either deleting them from the system file or putting this in your project configuration file:

    Ignore Keywords:
       about
       title

Altering Behavior

You can change the behavior of any comment type defined in the system file with your project configuration file. Just use Alter Comment Type and redefine any property.

    Alter Comment Type: Constant
       Scope: Always Global

Syntax Reference

    Ignore Keywords:
       [keyword]
       [keyword]
       ...

Ignores the keywords so that they're not recognized as starting Natural Docs comments anymore.

    Comment Type: [name]
    Alter Comment Type: [name]

Creates a new comment type or alters an existing one. You can use the project configuration folder's Comments.txt to change types found in the system one.

Comment Type Properties

    Display Name: [name]
    Plural Display Name: [name]

The singular and plural name of the comment type as it should appear in the output. Defaults to being the same as the comment type name. You can use this to change how they appear in the documentation without otherwise affecting their behavior.

    Display Name from Locale: [identifier]
    Plural Display Name from Locale: [identifier]

The identifiers in the current translation file that define the singular and plural names of the comment type as it should appear in the output. This is used by the system Comments.txt file to allow them to be displayed in the current language.

If you want to change the name of a comment type in the output you should remove these properties and use the versions without "from Locale" instead.

    Simple Identifier: [name]

The name of the comment type using only the letters A to Z. No spaces, numbers, symbols, or Unicode allowed. Defaults to the comment type name minus any unacceptable characters. This is used to generate things like CSS class names.

    Scope: [normal|start|end|always global]

How the comment affects scope. Defaults to normal.

Normal | Comments stay within the current scope.
Start | Comments start a new scope for all the comments beneath it, like class comments.
End | Comments reset the scope back to global for all the comments beneath it.
Always Global | Comments are defined as global, but do not change the scope for any other comments.

    Flags: [flag], [flag], ...

A combination of settings that apply to the comment type.

Code, File, or Documentation
Whether it's used to describe a code element, a file, or is a standalone documentation comment. Defaults to Code.
Variable Type
Whether it describes a code element that can be used as a variable's type.
Class Hierarchy or Database Hierarchy
Whether it describes a code element that should be included in the class or database hierarchy. Requires Scope: Start.
Enum
Whether it describes an enum.

    Keywords:
       [keyword]
       [keyword], [plural keyword]
       ...

A list of the comment type's keywords. Each line after the heading is the keyword and optionally its plural form for list comments.

    [Language] Keywords:
       [keyword]
       [keyword], [plural keyword]
       ...

A list of keywords that only apply to the comment type when using a specific programming language. Each line after the heading is the keyword and optionally its plural form for list comments.

Next: Languages.txt