Documenting Your Code: Reference

Date: Sat, 2 Aug 2008 08:21:29 +0000 Subject: added doc tool --- docs/tool/Help/documenting/reference.html | 146 ++++++++++++++++++++++ docs/tool/Help/documenting/walkthrough.html | 180 ++++++++++++++++++++++++++++ 2 files changed, 326 insertions(+) create mode 100644 docs/tool/Help/documenting/reference.html create mode 100644 docs/tool/Help/documenting/walkthrough.html (limited to 'docs/tool/Help/documenting') diff --git a/docs/tool/Help/documenting/reference.html b/docs/tool/Help/documenting/reference.html new file mode 100644 index 00000000..269ede89 --- /dev/null +++ b/docs/tool/Help/documenting/reference.html @@ -0,0 +1,146 @@ + + +Documenting Your Code: Reference - Natural Docs + + + +

Language Support Output Formats

Documenting
Your Code Keywords Running Troubleshooting

Organizing the Menu CSS Styles Topics and Keywords Languages, Indexes,
and Prototypes

Web Site Mailing Lists Message Boards Bugs and
Feature Requests

Documenting Your Code

Comments · Text Files · Keywords, Topics, and Scope · Linking
Formatting and Layout · Page Titles · Summaries · Javadoc Compatibility

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.

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 block comments or string together line comments. The only requirement is that the comments are not 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 stringing 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.

Boxes and Horizontal Lines

Natural Docs can also handle 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.
+//
+//////////////////////////////////////////////////////////////
+

Javadoc Style

If you have full language support, you can also use Javadoc-style comments to write Natural Docs documentation. To do this you repeat the last symbol on the first line of the comment once. The comment must appear directly above what it’s documenting, and you can omit the topic line if you want (the “Function: Multiply” part.)

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

If you omit the topic line and include any Javadoc tags in the comment, like @param, 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 the formatting options described on this page. You can have both styles in the same source file, but not in the same comment.

Perl POD

Perl users can also 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 in place of ND. None of them are 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 ever try to run POD on your code.

=nd
+
+Function: Multiply
+Multiplies two integers and returns the result.
+
+=cut
+

Text Files

Documentation can also be included in text files. Any file with a .txt extension appearing in the source tree and starting with a topic line will included in the documentation. 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.

Remember that the topic line is required to be the first line of content. If the first non-blank line is not in the “Function: Multiply” format the 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, the general program architecture, or anything else that isn’t directly tied to a source file.

Keywords, Topics, and Scope

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

The list of keywords is pretty predictable: Function, Class, Variable, etc. Just use what you’re documenting. There are many synonyms as well, so you can use keywords like Func, Procedure, Proc, Method and Constructor. Look at the full list of keywords to see everything that’s available.

The list of keywords is separated into topic types. Each type gets its own index, and which specific keyword you use doesn’t matter. Some also have scoping rules or other behavior as noted.

Scope

Like the code it’s documenting, Natural Docs topics have scope. This mostly has to do with linking: if you’re in a class you can link to its members by their name alone, but if you’re not, you have to use a notation like class.member or class::member.

If you have full language support and are documenting something that appears in the code, the scope will be handled automatically. If you’re using text files, have basic language support, or are including a topic that doesn’t correspond to something in the code, scoping follows these rules:

Everything after a class topic (or anything that says “Starts Scope”) is part of that class.
Everything after a section topic (or anything that says “Ends Scope”) is global again.
File topics (or anything that says “Always Global”) are global but do not change the scope for what follows.

List Topics

If you looked at the list, you saw that most of the keywords have plural forms. That’s for list topics, which let you document many small things without using the full syntax. Anything that appears in definition lists within that topic will be treated as if it had its own topic. It will appear in the indexes and be linkable, just like normal topics.

Function list topics will automatically break apart in the output as well, so it will look the same as if you documented each one individually.

Linking

Linking is the one place where Natural Docs has some negative effect on the readability of the comments. The alternative would be to automatically guess where links should be, but systems that do that can sometimes 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 topic you want to link to with angle brackets. Natural Docs will keep track off all the topics 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.

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

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.

If the topic has a summary sentence, hovering over the link will give it to you as a tooltip. If the topic has a prototype, that will be included as well. You can try it above.

Scope

If a topic is considered part of a class, they can be linked to using any of the three most common class/member notations: class.member, class::member, and class->member. Natural Docs will not be confused by <class->member>. Like in the language itself, if the topic you’re writing is in that class’ scope you can link to it simply as <member>.

If you have multi-level classes and packages, links can be relative as well. So if you’re in Project::UI::Window::Base and you want to link to Project::UI::Button::Base, just using <Button::Base> will work.

Plurals and Possessives

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. I’m not kidding: Foxes, Fox’s, Foxes’, Children, Mice, Alumni, Indices, Amoebae, Teeth, just try to trip it up.

URLs and E-Mail

You can also link to URLs and e-mail addresses. 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.
+

Visit http://www.website.com or send messages to em.nosp@m.ail@addre.nosp@m.ss.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>
+

Formatting and Layout

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

You can 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 Underline

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.
+
+Some text after the definition list.
+

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.

Some text after the definition list.

Remember that with definition lists, if you’re using the plural form of the keywords each entry can be linked to as if it had its own topic.

Code and Text Diagrams

You can add example code or text diagrams by starting each line with >, |, or :. If you have a vertical line or text box with the comment, you must separate these symbols from it with a space.

: 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). You can’t put any other content on these lines.

(start code)
+
+if (x == 0) {
+   DoSomething();
+}
+
+return x;
+
+(end)
+

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

return x;

You can also use example, diagram, or table instead of code. Just use whatever’s appropriate. Always flexible, it will accept begin for start and it will accept finish or done for end so you don’t have to remember the exact word.

Images

You can include images in your documentation by writing “(see filename)”. If you put it alone on a line it will be embedded in place.

This is the first paragraph.
+
+(see logo.gif)
+
+This is the second paragraph.
+

This is the first paragraph.

This is the second paragraph.

If it’s not alone on a line the image will appear after the end of the paragraph, the text will become a link to it, and the file name will be used as a caption.

This is the first paragraph (see logo.gif)  This is
+more of the first paragraph.
+

This is the first paragraph (see logo) This is more of the first paragraph.

logo

The image file names are relative to the source file the comment appears in or any directories specified with the -img command line option. You can use relative paths like (see images/logo.gif) and (see ../images/logo.gif), but you cannot use absolute paths, URLs, or specify a file that’s not in a folder included by -i or -img.

Natural Docs supports gif, jpg, jpeg, png, and bmp files.

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, 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 manually add group topics to divide long lists and make the summaries easier to navigate. Natural Docs will automatically group them by type if you do not, but sometimes you want to be more specific. You don’t need to provide a description, just adding a “Group: [name]” comment is sufficient. Note that once you manually add a group automatic grouping is completely 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

Example Class	A example class that does arithmetic with functions for people scared of operators.
Arithmetic Functions
Add	Adds two integers.
Subtract	Subtracts two integers.
Multiply	Multiplies two integers.
Divide	Divides two integers.
Comparison Functions
IsEqual	Returns whether two integers are equal.

Javadoc Compatibility

If you have full language support Natural Docs will also extract documentation from actual Javadoc comments, not just Natural Docs comments written with the Javadoc comment symbols. This provides you with a good method of migrating to Natural Docs as you don’t have to convert all of your existing documentation.

/**
+ * Multiplies two integers.
+ *
+ * @param x The first integer.
+ * @param y The second integer.
+ * @return The two integers multiplied together.
+ * @see Divide
+ */
+

Multiply

int Multiply (	int	x,
	int	y	)

Multiplies two integers.

Parameters

x	The first integer.
y	The second integer.

Returns

The two integers multiplied together.

Multiply

int Multiply (	int	x,
	int	y	)

Multiplies two integers and returns the result.

Okay, so that’s all you need, but probably not all you want. After all, you’ve got some real functions to document, not little one-liners. Here’s something more elaborate:

/*
+   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

x	The first integer.
y	The second integer.

Returns

The two integers multiplied together.

Every one of these comments you write (called topics) are going to start with a topic line in the format “keyword: title”. There are a lot of keywords, but they’re exactly what you’d expect: Function, Class, Variable, etc. There are also a lot of synonyms so instead of Function you could use Func, Procedure, Proc, Method, Constructor, etc. It’s designed so you can just use whatever it is you’re describing without memorizing anything. You can glance over the keyword list but you shouldn’t have to consult it very often.

The other part of the topic line is the title. It should match whatever it is you’re documenting, in this case the function name Multiply. Natural Docs is case sensitive even if your programming language isn’t, so make sure you match it closely or you might not get the prototype in your output, which is the little gray box. You don’t need to include the parameters in the title. In fact, it’s better if you don’t.

Parameters:
+
+Returns:
+
+See Also:
+

You can also define headings by skipping a line and ending the text with a colon. If you’re used to other documentation systems you may think there’s only a handful of headings to choose from, but any text formatted this way will become one. If you want a heading called Dependencies you can go right ahead and add it.

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

This is what’s called a definition list. You can use more than one line to finish the definition, as it won’t stop until you skip a line.

x - The first integer.
+y - The second integer with a long description.
+    This is still part of the description.
+
+This is a new paragraph because we skipped a line.
+

Indentation doesn’t matter either, so even if the second description line wasn’t indented to match the first, it would still be considered part of it.

<Divide>
+

This is how we link in Natural Docs, with angle brackets. There will be a lot more to say about this later, but for now I’ll just show you something cool. Hover over it in the output below:

Divide

You get that everywhere in your generated documentation.

Classes and Scope

So that’s good for our one function of questionable usefulness, but what if we have a whole class of questionable usefulness? We can document the class and it’s members the same way we documented the individual function, with a Natural Docs comment right above each element. We’ll go back to short descriptions to keep the example manageable.

/*
+   Class: Counter
+   A class that manages an incrementing counter.
+*/
+class Counter
+   {
+   public:
+
+      /*
+         Constructor: Counter
+         Initializes the object.
+      */
+      Counter()
+         {  value = 0;  };
+
+      /*
+         Function: Value
+         Returns the value of the counter.
+      */
+      int Value()
+         {  return value;  };
+
+      /*
+         Function: Increment
+         Adds one to the counter.
+      */
+      void Increment()
+         {  value++;  };
+
+   protected:
+
+      /*
+         Variable: value
+         The counter's value.
+      */
+      int value;
+   };
+

Everything’s the same, we just substituted Class and Variable for the Function keyword when it was appropriate. We also used Constructor, but we could have just as easily used Function there too. They’re both keywords for the same thing so it doesn’t matter.

Scope

Like the source code itself, Natural Docs topics have scope. Value and Increment are seen as part of class Counter, just like they are in the code. Why is this important? Linking. Linking from one topic to another has similar rules to how one function can call another. Since Value is in the same class as Increment, it’s topic can link to it with just <Increment>. However, linking to Increment from a different class would require <Counter.Increment> instead. You can actually use any of the three most common class/member notations: <Counter.Increment>, <Counter::Increment>, and <Counter->Increment>.

If your programming language has full language support, the scope is determined by the code and applied automatically. However, if you only have basic language support it follows these rules:

Any topic that appears under a Class topic (or anything that says Starts Scope) is part of that class.
Any topic that appears under a Section topic (or anything that says Ends Scope) is global again.
Any File topic (or anything that says Always Global) is global no matter what and doesn’t affect any other topics.

Chances are you would have written the same thing even if you didn’t know this and it would have just worked. You usually won’t need to think about them at all. However, it’s still good to be aware of them in case something doesn’t behave the way you expected it to.

You actually know enough to go start documenting now. I know Mr. ScrollBar says there’s more on this page you can learn, but if you want to skip out early, you can. Really. I don’t mind.

More Formatting

Okay then. On we go.

Paragraphs, Bold, and Underline

The syntax for these three is exactly what you would expect it to be.

*Bold text*
+
+_Underlined text_
+
+Paragraphs are broken by skipping lines.  So the two
+lines above each have their own paragraph, but these
+three lines are all part of the same one.
+

Bold text

Underlined text

Paragraphs are broken by skipping lines. So the two lines above each have their own paragraph, but these three lines are all part of the same one.

When underlining multiple words, you can use an underscore for each space or only put them at the edges like we did above. Both ways will work.

Bullet Lists

You can add bullet lists by starting a line with a dash, an asterisk, an o, or a plus. Like definition lists, bullets can span multiple lines and indentation doesn’t matter. To end a bullet you have to skip a line before doing something else.

- Bullet one.
+- Bullet two.
+  Bullet two continued.
+- Bullet three.
+
+Some text after the bullet list.
+

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

Some text after the bullet list.

Code and Text Diagrams

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

> a = b + c;
+> b++;
+

a = b + c;
b++;

If you have a long stretch, you can use (start code) and (end) instead.

(start code)
+
+if (x == 0) {
+   DoSomething();
+}
+
+return x;
+
+(end)
+

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

return x;

You can also use example, diagram, or table instead of code. Just use whatever’s appropriate.

As I mentioned before, we don’t want you to worry about memorizing minor details, so in that spirit it will also accept begin for start and finish or done for end. You can also write (end code) instead of just (end).

Images

You can include images in your documentation by writing “(see filename)”. If you put it alone on a line it will be embedded in place, or if you put it in a paragraph it will appear after it using the file name as a caption.

This is the first paragraph.
+
+(see logo.gif)
+
+This is the second paragraph (see logo.gif)  This
+is more of the second paragraph.
+

This is the first paragraph.

This is the second paragraph (see logo) This is more of the second paragraph.

logo

The image file names are relative to the source file the comment appears in, so if your file is C:\Project\SourceFile.cpp and your image is C:\Project\Images\Logo.gif, you would write (see Images/Logo.gif). However, you can also specify image directories in the command line with -img, so if all your source files are in C:\Project\Source and all your images are in C:\Project\Images, you can put “-img C:\Project\Images” on the command line and just use (see logo.gif) again.

License

This file is licensed under the GPL.

Remember that because of scope, the License topic will actually be considered part of Counter the way it’s listed above. You’d link to it from outside Counter with <Counter.License>. That idea may take some getting used to, but if an extra topic only applies to one class that’s actually the most appropriate way to do it. In this case it’s a license, so if it applies to the entire project instead you could put the comment above the class to make it global, just like moving a function there would.

Text Files

You can also add additional documentation with text files. If you put a file with a .txt extension in your source tree and start it with a topic line, it’s contents will be treated the same as if it were in a comment in your source code. That means you can define multiple topics within it, you can link between them and topics in your source code, and you can use all available formatting options.

Title: License
+
+This file is licensed under the GPL.
+
+I can link to <Counter> and <Counter.Increment>, and
+the documentation in that class can even link back
+with <License>.
+
+
+About: Second Topic
+
+I can create a *second* topic in here too, complete
+with formatting.
+

The thing some people forget though is that you must start it with a topic line, like “Title: License” above. This is how Natural Docs tells it apart from regular text files.

Abbreviated Syntax

Here’s another useful thing you may want to know about. Suppose you have a lot of little things to document, like constants. Writing a separate topic for each one can be very tedious, no matter how much you compress it:

// Constant: COUNTER_NORMAL
+// Causes the counter to increment normally.
+#define COUNTER_NORMAL 0
+
+// Constant: COUNTER_ODD
+// Causes the counter to only increment in odd numbers.
+#define COUNTER_ODD 1
+
+// Constant: COUNTER_EVEN
+// Causes the counter to only increment in even numbers.
+#define COUNTER_EVEN 2
+

One thing you may have noticed in the keyword list is that they almost all have plural forms. These are used to create what are called list topics. You define a topic using a plural keyword, and then anything appearing in a definition list within it creates a linkable symbol as if they each had their own topic. For example:

/*
+   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.
+*/
+#define COUNTER_NORMAL 0
+#define COUNTER_ODD 1
+#define COUNTER_EVEN 2
+

I would now be able to write <COUNTER_ODD> and have it work the same as it would with the first example.

Using the enum or enumeration keyword is special because it automatically behaves in a similar manner. 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 };
+

That’s it, you’re done with this walkthrough. You should know enough now to make very good use of Natural Docs. If you still want to know more, you can look in the reference for some of the smaller details we may have skipped over. Also, look at the Customizing pages on this web site for even more you can do.

\ No newline at end of file -- cgit 1.4.1