Natural Docs
Documenting Your Code

You document your code by putting Natural Docs content in the comments.  Before we go through all the specifics, here’s an example right off the bat so you have an idea of what it looks like.  Here’s your code:

/*
   Function: Multiply

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

And here’s what appears in your output:

Multiply

int Multiply (int x,
int y)

Multiplies two integers and returns the result. 

Here’s a more elaborate example.  This is overkill for this particular function, but you get the idea.

/*
   Function: Multiply

   Multiplies two integers.

   Parameters:

      x - The first integer.
      y - The second integer.

   Returns:

      The two integers multiplied together.

   See Also:

      <Divide>
*/
int Multiply (int x, int y)
   {  return x * y;  };

Multiply

int Multiply (int x,
int y)

Multiplies two integers. 

Parameters

xThe first integer. 
yThe second integer. 

Returns

The two integers multiplied together. 

See Also

Divide

int Add (int x,
int y)
Adds two integers.
int Subtract (int x,
int y)
Subtracts two integers.
int Multiply (int x,
int y)
Multiplies two integers.
int Divide (int x,
int y)
Divides two integers.
bool IsEqual (int x,
int y)
Returns whether two integers are equal.

Not too scary, huh?  Notice the comments are just as readable as the output.  No tags littered about, and the structure is very natural.  This was one of the goals of Natural Docs.  Anyway, on to the details.

Comments

There is no special comment style for Natural Docs.  You just embed Natural Docs topics into regular comments, and it’s pretty tolerant as far as style goes.  You can use multi-line comments or single line comments strung together.  The only requirement is that the comments are alone on a line.  Comments appearing on the same lines as code are ignored.

/*
   Function: Multiply
*/

//
// Function: Multiply
//

Note that when stringing single-line comments together, blank lines that you want to include in the documentation must start with the comment symbol as well.  If a line is completely blank, it’s considered the end of the comment and thus the end of the Natural Docs topic.

Natural Docs can also handle comment boxes and horizontal lines.  It doesn’t matter what symbols they use or how thick the lines are.  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 *
*********************/

// +--------------------+
// | Function: Multiply |
// +--------------------+

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

The only lines it doesn’t support are ones that use different symbols or are broken by spaces.

// -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
// |: This comment box is just too fancy.           :|
// |: - - - - - - - - - - - - - - - - - -           :|
// |: Not that a sane person would actually use it. :|
// -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Text Files

Alternately, documentation can be included in text files.  Any file with a .txt extension appearing in the source tree will be scanned for Natural Docs topics.  It will be treated the same as a source file, meaning it will appear in the menu, its topics will be in the indexes, and its topics can be linked to from anywhere in the documentation.  The only difference is you don’t need comment symbols.

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

Topics

As you may have guessed, a topic in Natural Docs starts with a “keyword: name” line.  You can have multiple topics per comment as long as you separate them with a blank line.  The keywords aren’t case sensitive.

The types of keywords are described below, and there are many synonyms for each one.  Your best bet is to just use what each topic is rather than to memorize a set of keywords, since the chances are good that Natural Docs does in fact have it for a keyword.

TopicA generic topic, such as a typedef, constant, or a piece of documentation that doesn’t directly correspond to something in the code.
FunctionA topic describing a function.  If the function appears immediately after the comment, it’s prototype will be included in the documentation.
VariableA topic describing a variable.  If the variable appears immediately after the comment, it’s prototype will be included in the documentation.
ClassA topic describing a class.  If you only have basic language support, all topics until the next class or section topic are considered part of the class.  Otherwise it’s detected automatically.
SectionA topic designating a major break in the file’s content.  It formats at the same level as class but doesn’t include a scope.  If you only have basic language support, section gets you out of a class’ scope if you need to document globals appearing after one in a file.  For organization within a class, you should use group instead.
GroupA topic designating the beginning of a group of related topics.  This is useful for splitting up large groups of topics in the documentation, which makes the summaries easier to navigate.  Once you manually add a group, though, the automatic grouping turns off for that class.
ListA topic describing a number of small topics.  The entries in any definition lists appearing in this section are linkable symbols, as if each one had its own topic.  This is useful when you have a large group of constants or other things that need to be documented and linkable but making a topic for each one would be too tedious.  Note that functions and variables documented this way will not have their prototypes included in the documentation.
FileA topic describing a file.  Although it can appear in a class, files are always global.  This is useful because a file may be tied primarily to a single class, and thus should be documented as part of it, but you would never want to reference it as class::file elsewhere in the documentation.

Look at the list of synonyms and you’ll see that you can pretty much use whatever word is most natural when describing the topic.

Formatting and Layout

As you saw in the more elaborate example, you can apply additional formatting and layout to your Natural Docs content, all in ways that will appear very natural in the source code.

Paragraphs

First of all, you break paragraphs by leaving blank lines between them.  So we have this in our content:

The first paragraph blah blah blah blah blah blah blah blah
blah blah blah blah blah blah blah blah blah blah blah blah
blah blah blah blah.

The second paragraph blah blah blah blah blah blah blah
blah blah blah blah blah blah blah blah blah blah blah blah
blah blah blah blah.

and we get this in our output:

The first paragraph blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah.

The second paragraph blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah.

Bold and Italics

You can apply bold to a stretch of text by surrounding it with asterisks.  You can apply underlining by surrounding it with underscores instead.  With underlining, it doesn’t matter if you use an underscore for every space between words or not; they’ll be converted to spaces if you do.

Some *bold text* and some _underlined text_
and yet _more_underlined_text_.

Some bold text and some underlined text and yet more underlined text.

Headings

You can add headings to your output just by ending a line with a colon and having a blank line above it.

Some text before the heading.

Heading:

Some text under the heading.

Some text before the heading.

Heading

Some text under the heading.

You must have a blank line above the heading or it will not work.  You can skip the blank after it but not before.

Bullet Lists

You can add bullet lists by starting a line with a dash, an asterisk, an o, or a plus.  Bullets can have blank lines between them if you want, and subsequent lines don’t have to be indented.  You end a list by skipping a line and doing something else.

- Bullet one.
- Bullet two.
  Bullet two continued.
- Bullet three.

Some text after the bullet list.

o Spaced bullet one.

o Spaced bullet two.
Spaced bullet two continued.

o Spaced bullet three.

Some text after the spaced bullet list.
  • Bullet one.
  • Bullet two.  Bullet two continued.
  • Bullet three.

Some text after the bullet list.

  • Spaced bullet one.
  • Spaced bullet two.  Spaced bullet two continued.
  • Spaced bullet three.

Some text after the spaced bullet list.

Definition Lists

You can add a definition list by using the format below, specifically “text space dash space text”.  Like bullet lists, you can have blank lines between them if you want, subsequent lines don’t have to be indented, and you end the list by skipping a line and doing something else.

First  - This is the first item.
Second - This is the second item.
         This is more of the second item.
Third  - This is the third item.
This is more of the third item.
FirstThis is the first item.
SecondThis is the second item.  This is more of the second item.
ThirdThis is the third item.  This is more of the third item.

Remember that with definition lists, if the parent topic is “list” or one of its synonyms, each entry is a symbol and can be linked to just as if it had its own topic.

Code and Text Diagrams

Finally, you can add example code or text diagrams by starting each line with >, |, or :.

: a = b + c;

>   +-----+     +-----+
>   |  A  | --> |  B  |
>   +-----+     +-----+
>                  |
>               +-----+
>               |  C  |
>               +-----+
a = b + c;
+-----+     +-----+
|  A  | --> |  B  |
+-----+     +-----+
               |
            +-----+
            |  C  |
            +-----+

For long stretches, this may be too tedious.  You can start a code section by placing “(start code)” or just “(code)” alone on a line.  You end it with either “(end code)” or just “(end)”.  Remember that they must be the only things present on that line to work.

(start code)

if (x == 0) {
   DoSomething();
}

return x;

(end)
if (x == 0) {
   DoSomething();
}

return x;

You can use “example”, “diagram”, or “table” in addition to “code”.  Just use whatever’s appropriate.  Always flexible, you can also substitute “begin” for “start” and “finish” or “done” for “end” if you want.

Linking

Linking is the one place where Natural Docs has some negative effect on the readability of the comments.  Of course, the alternative would be to automatically guess where links should be, but systems that do that typically pepper your sentences with unintentional links to functions called “is” or “on”.  However, the Natural Docs syntax is still as minimal as possible.  Simply surround any symbol you want to link to with angle brackets.  Natural Docs will keep track off all the symbols and where they are defined, so you don’t need to use HTML-like syntax or remember what file anything is in.  Also, if the link can’t be resolved to anything, Natural Docs leaves the angle brackets in the output so if something wasn’t intended to be a link (such as “#include <somefile.h>”) it won’t be mangled.

Let's link to function <Multiply>.

Let’s link to function Multiply

If the target has a summary sentence, hovering over the link will give it to you as a tooltip.  If the target is a function or variable, it will also give you its prototype.  You can try it above.

How do you define symbols?  Well, every Natural Docs topic defines a symbol corresponding to its name.  If you use a list topic, every item in any of its definition lists is also a symbol.

Symbols can have scope.  All symbols defined after a class topic until the next class or section topic are considered part of that class (except file topics, which are always global.)  They are linked to using any of the three most common class/member notations:  class.member, class::member, and class->member.  No, Natural Docs will not be confused by <class->member>.  Like in the language itself, if you’re currently in that class’ scope you can link to it simply as <member>.

Also note that when linking to functions, it doesn’t matter if you include empty parenthesis or not.  Both <Function> and <Function()> will work.  However, if you documented the function with parameters as part of the name, you will need to include those parameters whenever linking to it.  It is recommended that you only include parameters in the topic name if you need to distinguish between two functions with the same name.

Links and symbols are case sensitive, regardless of whether the language is or not.

Finally, to make the documentation easier to write and easier to read in the source file, you can include plurals and possessives inside the angle brackets.  In other words, you don’t have to use awkward syntax like <Object>s, although that’s supported as well.  You can simply write <Objects> and it will link to the symbol Object just fine.  It can handle any plural and/or possessive form you can throw at it.  <Foxes>, <Children>, <Mice>, <Class’>, <Alumni’s>, it will actually handle it all.

URLs and E-Mail

You can also link to URLs and e-mail addresses in your comments.  It will detect them automatically, but you can also put them in angle brackets if you like.

Visit <http://www.website.com> or send messages to
email@address.com.

E-mail addresses are protected in a way that should avoid spam crawlers.  Although the link above looks and acts like a regular link (try it) the HTML code actually looks like this:

<a href="#" 
 onClick="location.href='mai' + 'lto:' + 'em' + 'ail' + '@'
          + 'addre' + 'ss.com'; return false;">
    em<span style="display: none">.nosp@m.</span>ail
    <span>@</span>
    addre<span style="display: none">.nosp@m.</span>ss.com
</a>
Page Titles

Natural Docs automatically determines the page title as follows:

  • If there’s only one topic in the file, that topic’s title becomes the page title.
  • Otherwise, if the first topic in the file is a class, section, or file topic, that topic’s title becomes the page title.
  • Otherwise, the file name becomes the page title.

This should be enough for most people.  However, if you don’t like the page title Natural Docs has chosen for you, add a “Title: [name]” comment to the top of the file to override it.  “Title” is a synonym of Section, so that will satisfy the second rule and make it the page title.

Summaries

Summaries are automatically generated for every file, class, and section.  You don’t have to do anything special to get them.

There are two things you may want to keep in mind when documenting your code so that the summaries are nicer.  The first is that they use the first sentence in the topic as the description, so long as it’s plain text and not something like a bullet list.  It will also appear in the tooltip whenever that topic is linked to.

The second is that you may want to use group topics to divide long lists and make the summaries is easier to navigate.  You don’t need to provide a description, just adding a “Group: [name]” comment is sufficient.  Note, however, that once you manually add a group automatic grouping is turned off for that class.

Here’s an example summary.  Note that as before, when you hover over a link, you’ll get the prototype and summary line as a tooltip.

Summary
A example class that does arithmetic with functions for people scared of operators.
Adds two integers.
Subtracts two integers.
Multiplies two integers.
Divides two integers.
Returns whether two integers are equal.
Indexes

Natural Docs will generate indexes for your project automatically, both general and by type.  If you don’t want them, just delete them from the menu and they won’t come back unless you allow them to.

That’s It!

Here’s our overkill example again, just to refresh your memory.  Visit our website to see examples of what a complete project’s output would look like.

Important: Make sure you read the traps page so you don’t make some of the more common mistakes.  It’s better now than trying to figure out why it isn’t working later.

/*
   Function: Multiply

   Multiplies two integers.

   Parameters:

      x - The first integer.
      y - The second integer.

   Returns:

      The two integers multiplied together.

   See Also:

      <Divide>
*/
int Multiply (int x, int y)
   {  return x * y;  };

Multiply

int Multiply (int x,
int y)

Multiplies two integers. 

Parameters

xThe first integer. 
yThe second integer. 

Returns

The two integers multiplied together. 

See Also

Divide