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.
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.
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.
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.
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
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
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
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.
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.
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.