Code sections in Natural Docs 1.x were designated with (start code) and (end) lines.  This is still supported so all of your old comments will still work.  However, the new syntax provides a much better visual break.  Start a line with three dashes, equals signs, or underscores and then put the Code keyword.  End it by putting the same three characters alone.

This is a normal paragraph.

--- Code
int x = 12;
int y = 0;
---

This is a normal paragraph.

Actually, the syntax is at least three characters.  You can add more for better visual separation, and you can put some after the keyword as well.

This is a normal paragraph.

==== Code ====
int x = 12;
int y = 0;
==============

This is a normal paragraph.

It only recognizes the characters you started it with as the ending, so if the others appear in the code Natural Docs will not be confused.

=== Code
int x = 12;
---
int y = 0;
===

You can also use a language name instead of Code to tell Natural Docs which syntax highlighter to use.

___ Perl ___

my $x = 12;
my $y = 0;
____________

You can even switch from one to another without ending each block separately.

----- C# -----
int x = 12;
int y = 0;
---- Perl ----
my $x = 12;
my $y = 0;
--------------

Language names work with the old syntax as well, so you can use (start C#) or (perl) if you want to.

Bullet lists can now have multiple levels.  Each one has to be indented at least two spaces more than the previous one, but otherwise they can be any length apart.

- Level 1

   - Level 2

      - Level 3

         - Level 4

   - Level 2 again

When you're creating a definition list, you can now have more than one paragraph in the definition.  Just indent the additional paragraphs at least two spaces.

Item 1 - This is the first paragaph of the definition.

         This is the second paragraph of the definition.
         Indenting it enough to line up is optional.

Item 2 - This is the first paragraph of the definition.

  This is the second paragraph of the definition.
  It only needs at least two additional spaces.

Item 3 - This is the first paragraph of the definition.

This is a normal paragraph.  It's not part of the definition
because it's not indented.

This also works in bullet lists.  Each one just has to be indented two spaces past where the bullet was.

- Paragraph on level 1

  Another paragraph on level 1

   - Paragraph on level 2

     Another paragraph on level 2

The previous way you made a heading was to skip a line and then end the next one with a colon.  The problem was that it can be triggered accidentally:

This is how you initialize a variable:

> int x = 12;

I asked the user polling mailing list about requiring title-case and people were okay with it, so now that's what you need to use.

Title-case means all of the words are capitalized except for short ones like "and" and "the", like in the title of a book.  The first and last words always have to be capitalized, which means these are headings:

Parameters:

This or That:

A Day in the Life:

and these are not:

You do it like this:

or:

If you ever want to force a heading, just use two colons.

This is a heading even though it's not in title-case::

Literal links are when you surround something with angle brackets, like <FunctionName()> or <john@mycompany.com>.  Named links are when you have separate text and targets, which is done with the "at" keyword because it flows nicely in a sentence.

<E-mail me at john@mycompany.com> or visit our <web site at http://www.mycompany.com>.

That gets converted to "E-mail me or visit our web site."  That still works, but now you can use a colon as well, since sometimes "at" doesn't seem to fit.

Contact Info:
- <E-Mail: john@mycompany.com>
- <Web Site: http://www.mycompany.com>

If you have multiple functions that only differ by parameters, Natural Docs will just link to the first one.  To link to a different one you had to include parentheses in the title and match them in every link.

// Function: MyFunction
void MyFunction (float f) { ... }

// Function: MyFunction(2)
void MyFunction (int x, int y) { ... }

// Topic: Notes
// This is how you link to <MyFunction(2)>.

This is still supported.  However, Natural Docs 2.0 will also use prototypes to interpret links, so you can do this instead:

// Function: MyFunction
void MyFunction (float f) { ... }

// Function: MyFunction
void MyFunction (int x, int y) { ... }

// Topic: Notes
// You can link by type with <MyFunction(int, int)> or
// by parameter name with <MyFunction(x, y)>.

A few people have asked for this.  You can now add prototypes directly to your comments by using the code syntax but with the Prototype keyword instead.  This is useful for documenting things that cannot easily be documented otherwise.  For example, I use it to document the columns and indexes of my database tables.

Database Column: TopicID

    --- Prototype ---
    TopicID INTEGER PRIMARY KEY NOT NULL
    -----------------

    The identifier of an individual topic, which will
    be unique across the database.

When you have full language support Natural Docs can read Javadoc comments in addition to its own.  With 2.0 it can also read Microsoft's XML format.

/// <summary>Description of MyFunction.</summary>
/// <param name="x">Description of X parameter</param>
/// <param name="y">Description of Y parameter</param>
void MyFunction (int x, int y) { ... }

It doesn't support its more advanced features so you shouldn't rely on this if you're going to continue to use Microsoft's format, but if you have a bunch of existing content Natural Docs should be able to read most of it.