RubyGems - bixbite - Versions diffs - 0.1.0 - Mend

bixbite 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (194) hide show

data/template/assets/naturaldocs/NaturalDocs/Help/customizinglanguages.html ADDED

@@ -0,0 +1,52 @@
+<html><head><title>Customizing Natural Docs Languages</title><link rel=stylesheet type="text/css" href="styles.css"><link rel=stylesheet type="text/css" href="examples.css"><style type="text/css"><!--
+        .InMainFile {
+            padding: 1ex 2ex;
+            margin: 1em 0;
+            font: italic 9pt Verdana, sans-serif;
+            line-height: 150%;
+            background-color: #F8F8F8;
+            }
+        .InMainFile code {
+            font-size: 9pt;
+            }
+        .EnumTable {
+            margin: .5em 5ex;
+            }
+        .EnumOption {
+            font-weight: bold;
+            padding-right: 2ex;
+            }
+--></style><script language=JavaScript src="javascript/PNGHandling.js"></script><script language=JavaScript src="javascript/BrowserStyles.js"></script></head><body marginwidth=0 marginheight=0 leftmargin=0 topmargin=0><script language=JavaScript><!--
+OpeningBrowserTags();// --></script>
+<!-- saved from url=(0026)http://www.naturaldocs.org -->
+<table width=100% border=0 cellspacing=0 cellpadding=0><tr><td colspan=3 class=Header><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td><img src="images/header/leftside.png" width=30 height=75><a href="index.html"><img src="images/header/logo.png" width=524 height=75 alt="Natural Docs"></a></td><td align=right><img src="images/header/rightside.png" width=30 height=75></td></tr></table></td></tr><tr><td><img src="images/header/overleftmargin.png" width=10 height=6></td><td class=SideMenuTop><img src="images/header/overmenu.png" width=14 height=6></td><td class=BodyTop><img src="images/header/overbody.png" width=24 height=6></td></tr><tr><td></td><td class=SideMenu nowrap><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/about.png" width=52 height=13 alt="About"></div><div class=SideMenuBody><a href="languages.html" class=SideMenuEntry>Language Support</a><a href="output.html" class=SideMenuEntry>Output Formats</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/using.png" width=45 height=13 alt="Using"></div><div class=SideMenuBody><a href="documenting.html" class=SideMenuEntry>Documenting<br>Your Code</a><a href="keywords.html" class=SideMenuEntry>Keywords</a><a href="running.html" class=SideMenuEntry>Running</a><a href="troubleshooting.html" class=SideMenuEntry>Troubleshooting</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/customizing.png" width=96 height=13 alt="Customizing"></div><div class=SideMenuBody><a href="menu.html" class=SideMenuEntry>Organizing the Menu</a><a href="styles.html" class=SideMenuEntry>CSS Styles</a><a href="customizingtopics.html" class=SideMenuEntry>Topics and Keywords</a><span class=SideMenuEntry id=SelectedSideMenuEntry>Languages, Indexes,<br>and Prototypes</span></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/community.png" width=86 height=13 alt="Community"></div><div class=SideMenuBody><a href="http://www.naturaldocs.org/" class=SideMenuEntry>Web Site</a><a href="http://www.naturaldocs.org/mailinglist.html" class=SideMenuEntry>Mailing Lists</a><a href="http://www.naturaldocs.org/messageboards.html" class=SideMenuEntry>Message Boards</a><a href="http://www.naturaldocs.org/bugs.html" class=SideMenuEntry>Bugs and<br>Feature Requests</a></div></div></td><td class=Body width=100%><div class=PageTitle>Customizing Languages</div><div class=TOC><a href="#LanguagesTxt">Languages.txt</a> &middot; <a href="#FileExtensions">File Extensions</a> &middot; <a href="#AddingLanguages">Adding Languages</a> &middot; <a href="#Prototypes">Prototypes</a><br><a href="#IndexPrefixes">Index Prefixes</a> &middot; <a href="#SpecialLanguages">Special Languages</a> &middot; <a href="#SyntaxReference">Syntax Reference</a></div><div class=Topic><a name="LanguagesTxt"></a><div class=TopicTitle>Languages.txt</div><p>Natural Docs has two files called <code>Languages.txt</code>: one in its Config directory, and one in <a href="running.html#CommandLine">your project directory.</a>&nbsp; These control the language, index prefix, and prototype features of Natural Docs.</p><p>You should edit the one in your project directory whenever possible.&nbsp; It keeps your changes separate and easier to manage, plus you don&rsquo;t have to reapply them whenever you upgrade.&nbsp; Editing the one in Natural Docs&rsquo; Config directory would be better only if you&rsquo;re using Natural Docs with a lot of projects and would like the changes to apply everywhere.</p><p>Note that unlike other Natural Docs configuration files, comments can only appear on their own lines.&nbsp; They cannot appear after something else on a line because settings may need to use the <code>#</code> symbol.&nbsp; Also, all lists are space-separated instead of comma-separated, again because some settings may need to use the comma symbol.</p></div><div class=Topic><a name=FileExtensions></a><div class=TopicTitle>File Extensions</div><p>If Natural Docs doesn&rsquo;t recognize a file extension you use for your code, it&rsquo;s not a problem.&nbsp; You can alter the language definition from your project file to add them.</p><pre class=Example>Alter Language: <i>[your language]</i>
+   Add Extensions: cxx hxx</pre><p>On the other hand, if it&rsquo;s scanning some files you don&rsquo;t want it to scan, you can exclude extensions as well.&nbsp; Just add this to the top of your file:</p><pre class=Example>Ignore Extensions: c cpp</pre><p>In this example, Natural Docs will ignore C++ source files, thus only scanning the headers.</p></div><div class=Topic><a name=AddingLanguages></a><div class=TopicTitle>Adding Languages</div><p>You can add <a href="languages.html">basic language support</a> for any programming language just by editing these configuration files.&nbsp; Here are the most important settings:</p><pre class=Example>Language: Fictional
+   Extensions: fsrc fhdr
+   Shebang Strings: fictional
+   Line Comment: //
+   Block Comment: /* */
+   Package Separator: ::</pre><p>This tells Natural Docs that any files with the .fsrc or .fhdr extensions are part of our fictional programming language.&nbsp; Also, any .cgi or extensionless files that have &ldquo;fictional&rdquo; in the shebang (<code>#!</code>) line are part of it as well.&nbsp; Line comments start with <code>//</code> and block comments appear between <code>/*</code> and <code>*/</code>.&nbsp; The default package separator is <code>::</code>.&nbsp; Not too hard, huh?</p><p>You can also add settings to <a href="#IndexPrefixes">ignore prefixes in the index</a> and <a href="#Prototypes">detect prototypes</a>, but those are dealt with in their own sections on this page.</p></div><div class=Topic><a name=Prototypes></a><div class=TopicTitle>Prototypes</div><p>So you&rsquo;ve <a href="#AddingLanguages">added a new language</a> and want to detect prototypes.&nbsp; Or perhaps you <a href="customizingtopics.html#AddingTopicTypes">added a custom topic type</a> and want to detect prototypes for that as well.&nbsp; Here&rsquo;s an example of the properties you need:</p><pre class=Example>Function Prototype Enders: ; {
+Variable Prototype Enders: ; =</pre><p>The algorithm for finding prototypes is very simple, yet it works really well in practice.&nbsp; All the code following the comment is grabbed until it reaches an ender symbol or another comment.&nbsp; Ender symbols appearing inside parenthesis, brackets, braces, or angle brackets don&rsquo;t count.&nbsp; If it reaches an ender symbol and somewhere in that code is the topic title, the code is accepted as the prototype.</p><p>So in the example above, variables end at semicolons (the end of the declaration) or equal signs (the default value expression, which we don&rsquo;t want to include.)&nbsp; Since the Natural Docs comment for the variable should have appeared right before the definition, that leaves us with the name and type.&nbsp; Functions are handled similarly: they end at a semicolon (the end of a predeclaration) or an opening brace (the beginning of the body) leaving us with the name, parameters, and return type.</p><p>You can do this with any topic type, including custom ones.&nbsp; Any prototypes that look like they have parameters will be formatted as such automatically.</p><div class=SubTopic>Line Breaks</div><p>For some languages, line breaks are significant.&nbsp; To have them end a prototype, use <code>\n</code>.&nbsp; If it has an extender symbol that allows the code to continue on the next line, you can specify that as well.</p><pre class=Example>Function Prototype Ender: \n
+Variable Prototype Ender: \n =
+Line Extender: _</pre><div class=SubTopic>Colors</div><p>If you&rsquo;re collecting prototypes for a custom topic type, they will not automatically get their own background color like the other types have.&nbsp; <a href="styles.html#CommonCustomizations">You have to define it via CSS.</a></p></div><div class=Topic><a name=IndexPrefixes></a><div class=TopicTitle>Index Prefixes</div><p>Natural Docs has the ability to ignore prefixes in the indexes.&nbsp; This is necessary because in certain languages, variables are prefixed with <code>$</code> or other symbols and we don&rsquo;t want them to get all grouped together under the symbols heading.&nbsp; Instead, they appear in the sidebar and are sorted as if they&rsquo;re not there.</p><div class=NDIndex><table border=0 cellspacing=0 cellpadding=0><tr><td class=IHeading id=IFirstHeading>A</td><td></td></tr><tr><td class=ISymbolPrefix id=IFirstSymbolPrefix>&nbsp;</td><td class=IEntry><span class=ISymbol>AddProperty</span>, <span class=IParent>SomeClass</span></td></tr><tr><td class=ISymbolPrefix>$</td><td class=IEntry><span class=ISymbol>amount</span></td></tr><tr><td class=ISymbolPrefix id=ILastSymbolPrefix>&nbsp;</td><td class=IEntry><span class=ISymbol>Average</span></td></tr></table></div><p>However, we can take advantage of this simply to get around coding conventions.&nbsp; Suppose you prefix all your class names with C.&nbsp; They&rsquo;d all form one gigantic group under C in the index.&nbsp; If you want, you can have it ignored so CCat, CDog, and CMouse get filed under C, D, and M instead.&nbsp; Just add this to your languages file:</p><pre class=Example>Alter Language: <i>[your language]</i>
+   Add Ignored Class Prefix in Index: C</pre><p>Now C is ignored in your indexes:</p><div class=NDIndex><table border=0 cellspacing=0 cellpadding=0><tr><td class=IHeading id=IFirstHeading>A</td><td></td></tr><tr><td class=ISymbolPrefix id=IFirstSymbolPrefix>C</td><td class=IEntry><span class=ISymbol>Account</span></td></tr><tr><td class=ISymbolPrefix>C</td><td class=IEntry><span class=ISymbol>AccountHolder</span></td></tr><tr><td class=ISymbolPrefix>&nbsp;</td><td class=IEntry><span class=ISymbol>AddProperty</span>, <span class=IParent>SomeClass</span></td></tr><tr><td class=ISymbolPrefix>$</td><td class=IEntry><span class=ISymbol>amount</span></td></tr><tr><td class=ISymbolPrefix id=ILastSymbolPrefix>&nbsp;</td><td class=IEntry><span class=ISymbol>Average</span></td></tr></table></div><p>You can include any number of prefixes and can do this for any topic type.&nbsp; So if you have a bunch of functions that start with <code>COM_</code> and <code>DB_</code>, you can ignore them too:</p><pre class=Example>Alter Language: <i>[your language]</i>
+   Add Ignored Class Prefix in Index: C
+   Add Ignored Function Prefixes in Index: COM_ DB_</pre></div><div class=Topic><a name=SpecialLanguages></a><div class=TopicTitle>Special Languages</div><p>There are two languages with special properties: Shebang Script and Text File.</p><p>Shebang Script allows you to define the file extensions where the language is really determined by the shebang (<code>#!</code>) line within it.&nbsp; For example, .cgi files.&nbsp; If Natural Docs finds a .cgi file, it sees that it&rsquo;s a Shebang Script so it opens it up to parse it&rsquo;s shebang line.&nbsp; It then searches it for substrings defined by other languages&rsquo; <code>Shebang String</code> settings to find out what language it really is.&nbsp; Files with no extension are always treated this way.</p><p>With Text File, the entire file is treated like a comment.&nbsp; There are no comment symbols required, you can just put Natural Docs content there in plain text.&nbsp; The most important setting is <code>Extensions</code>.</p><p>However, since it is possible to document classes, functions, etc. in text files, they also have their own <code>Package Separator</code> and <code>Ignored <i>[type]</i> Prefixes in Index</code> settings.&nbsp; To make things easier on you, by default it copies these settings from whichever language has the most source files in your project.&nbsp; You can override this by manually setting them, but you shouldn&rsquo;t need to.</p></div><div class=Topic><a name=SyntaxReference></a><div class=TopicTitle>Syntax Reference</div><p>Unlike other Natural Docs configuration files, comments can only appear on their own lines.&nbsp; They cannot appear after something else on a line because settings may need to use the <code>#</code> symbol.&nbsp; Likewise, lists are separated with spaces instead of commas because commas themselves may need to appear on the list.</p><p>Singular and plural forms are generally both supported, so you can write <code>Extension</code> or <code>Extensions</code>.&nbsp; It doesn&rsquo;t matter if they match how many items are set.&nbsp; Also, you can use either <code>Ignore</code> or <code>Ignored</code>.</p><pre class=Example>Ignore Extensions: <i>[extension] [extension]</i> ...</pre><p>Causes the listed file extensions to be ignored, even if they were previously defined to be part of a language.&nbsp; The list is space-separated.&nbsp; ex. &ldquo;<code>Ignore Extensions: cvs txt</code>&rdquo;</p><pre class=Example>Language: <i>[name]</i>
+Alter Language: <i>[name]</i></pre><p>Creates a new language or alters an existing one.&nbsp; Names can use any characters.&nbsp; Note the <a href="#SpecialLanguages">special behavior for languages named Shebang Script and Text File</a>.</p><p>If you&rsquo;re altering an existing language and a property has an <code>[Add/Replace]</code> form, you have to specify whether you&rsquo;re adding to or replacing the list if that property has already been defined.</p><div class=SubTopic>General Language Properties</div><pre class=Example>Extensions: <i>[extension] [extension]</i> ...
+<i>[Add/Replace]</i> Extensions: <i>[extension] [extension]</i> ...</pre><p>Defines file extensions for the language&rsquo;s source files.&nbsp; The list is space-separated.&nbsp; ex. &ldquo;<code>Extensions: c cpp</code>&rdquo;.&nbsp; You can use extensions that were previously used by another language to redefine them.&nbsp; You can use <code>*</code> to specify all undefined extensions.</p><pre class=Example>Shebang Strings: <i>[string] [string]</i> ...
+<i>[Add/Replace]</i> Shebang Strings: <i>[string] [string]</i> ...</pre><p>Defines a list of strings that can appear in the shebang (<code>#!</code>) line to designate that it&rsquo;s part of this language.&nbsp; They can appear anywhere in the line, so <code>php</code> will work for &ldquo;<code>#!/user/bin/php4</code>&rdquo;.&nbsp; You can use strings that were previously used by another language to redefine them.</p><pre class=Example>Ignore Prefixes in Index: <i>[prefix] [prefix]</i> ...
+Ignore <i>[type]</i> Prefixes in Index: <i>[prefix] [prefix]</i> ...
+<i>[Add/Replace]</i> Ignored Prefixes in Index: <i>[prefix] [prefix]</i> ...
+<i>[Add/Replace]</i> Ignored <i>[type]</i> Prefixes in Index: <i>[prefix] [prefix]</i> ...</pre><p>Specifies prefixes that should be ignored when sorting symbols for an index.&nbsp; Can be specified in general or for a specific topic type.&nbsp; The prefixes will still appear, the symbols will just be sorted as if they&rsquo;re not there.&nbsp; For example, specifying <code>ADO_</code> for functions will mean that <code>ADO_DoSomething</code> will appear under D instead of A.</p><div class=SubTopic>Basic Language Support Properties</div><p>These attributes are only available for languages with basic language support.</p><pre class=Example>Line Comments: <i>[symbol] [symbol]</i> ...</pre><p>Defines a space-separated list of symbols that are used for line comments, if any.&nbsp; ex. &ldquo;<code>Line Comment: //</code>&rdquo;.</p><pre class=Example>Block Comments: <i>[opening symbol] [closing symbol] [o.s.] [c.s.]</i> ...</pre><p>Defines a space-separated list of symbol pairs that are used for block comments, if any.&nbsp; ex. &ldquo;<code>Block Comment: /* */</code>&rdquo;.</p><pre class=Example>Enum Values: <i>[global|under type|under parent]</i></pre><p>Defines the behavior of enum values.&nbsp; The default is global.</p><table border=0 cellspacing=0 cellpadding=0 class=EnumTable><tr><td class=EnumOption>Global</td><td>Enum values are always global and will be referenced as &ldquo;Value&rdquo;.</td></tr><tr><td class=EnumOption>Under Type</td><td>Enum values appear under the type and will be referenced as &ldquo;Package.Enum.Value&rdquo;.</td></tr><tr><td class=EnumOption>Under Parent</td><td>Enum values appear under the parent and will be referenced as &ldquo;Package.Value&rdquo;</td></tr></table><pre class=Example><i>[type]</i> Prototype Enders: <i>[symbol] [symbol]</i> ...</pre><p>When defined, Natural Docs will attempt to collect prototypes from the code following the specified topic type.&nbsp; It grabs code until the first ender symbol or the next Natural Docs comment, and if it contains the topic name, it serves as its prototype.&nbsp; Use <code>\n</code> to specify a line break.&nbsp; ex. &ldquo;<code>Function Prototype Enders: { ;</code>&rdquo;, &ldquo;<code>Variable Prototype Enders: = ;</code>&rdquo;. </p><pre class=Example>Line Extender: <i>[symbol]</i></pre><p>Defines the symbol that allows a prototype to span multiple lines if normally a line break would end it.</p><pre class=Example>Perl Package: <i>[perl package]</i></pre><p>Specifies the Perl package used to fine-tune the language behavior in ways too complex to do in this file.</p><div class=SubTopic>Full Language Support Properties</div><p>These attributes are only available for languages with full language support.</p><pre class=Example>Full Language Support: <i>[perl package]</i></pre><p>Specifies the Perl package that has the parsing routines necessary for full language support.</p></div></td></tr><tr><td></td><td class=SideMenuBottom><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td class=SideMenuBottomLeft><img src="images/menu/bottomleft.png" width=18 height=19></td><td class=SideMenuBottomRight><img src="images/menu/bottomright.png" width=18 height=19></td></tr></table></td><td class=BodyBottom>Copyright &copy; 2003-2008 Greg Valure</td></tr></table><script language=JavaScript><!--
+ClosingBrowserTags();// --></script></body></html>

data/template/assets/naturaldocs/NaturalDocs/Help/customizingtopics.html ADDED

@@ -0,0 +1,74 @@
+<html><head><title>Customizing Natural Docs Topics</title><link rel=stylesheet type="text/css" href="styles.css"><style type="text/css"><!--
+        .InMainFile {
+            padding: 1ex 2ex;
+            margin: 1em 0;
+            font: italic 9pt Verdana, sans-serif;
+            line-height: 150%;
+            background-color: #F8F8F8;
+            }
+        .InMainFile code {
+            font-size: 9pt;
+            }
+        .ScopeTable {
+            margin: .5em 5ex;
+            }
+        .ScopeOption {
+            font-weight: bold;
+            padding-right: 2ex;
+            }
+--></style><script language=JavaScript src="javascript/PNGHandling.js"></script><script language=JavaScript src="javascript/BrowserStyles.js"></script></head><body marginwidth=0 marginheight=0 leftmargin=0 topmargin=0><script language=JavaScript><!--
+OpeningBrowserTags();// --></script>
+<!-- saved from url=(0026)http://www.naturaldocs.org -->
+<table width=100% border=0 cellspacing=0 cellpadding=0><tr><td colspan=3 class=Header><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td><img src="images/header/leftside.png" width=30 height=75><a href="index.html"><img src="images/header/logo.png" width=524 height=75 alt="Natural Docs"></a></td><td align=right><img src="images/header/rightside.png" width=30 height=75></td></tr></table></td></tr><tr><td><img src="images/header/overleftmargin.png" width=10 height=6></td><td class=SideMenuTop><img src="images/header/overmenu.png" width=14 height=6></td><td class=BodyTop><img src="images/header/overbody.png" width=24 height=6></td></tr><tr><td></td><td class=SideMenu nowrap><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/about.png" width=52 height=13 alt="About"></div><div class=SideMenuBody><a href="languages.html" class=SideMenuEntry>Language Support</a><a href="output.html" class=SideMenuEntry>Output Formats</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/using.png" width=45 height=13 alt="Using"></div><div class=SideMenuBody><a href="documenting.html" class=SideMenuEntry>Documenting<br>Your Code</a><a href="keywords.html" class=SideMenuEntry>Keywords</a><a href="running.html" class=SideMenuEntry>Running</a><a href="troubleshooting.html" class=SideMenuEntry>Troubleshooting</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/customizing.png" width=96 height=13 alt="Customizing"></div><div class=SideMenuBody><a href="menu.html" class=SideMenuEntry>Organizing the Menu</a><a href="styles.html" class=SideMenuEntry>CSS Styles</a><span class=SideMenuEntry id=SelectedSideMenuEntry>Topics and Keywords</span><a href="customizinglanguages.html" class=SideMenuEntry>Languages, Indexes,<br>and Prototypes</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/community.png" width=86 height=13 alt="Community"></div><div class=SideMenuBody><a href="http://www.naturaldocs.org/" class=SideMenuEntry>Web Site</a><a href="http://www.naturaldocs.org/mailinglist.html" class=SideMenuEntry>Mailing Lists</a><a href="http://www.naturaldocs.org/messageboards.html" class=SideMenuEntry>Message Boards</a><a href="http://www.naturaldocs.org/bugs.html" class=SideMenuEntry>Bugs and<br>Feature Requests</a></div></div></td><td class=Body width=100%><div class=PageTitle>Customizing Topics</div><div class=TOC><a href="#Topicstxt">Topics.txt</a> &middot; <a href="#TopicTypesVsKeywords">Topic Types vs. Keywords</a> &middot; <a href="#AddingTopicTypes">Adding Topic Types</a><br><a href="#ChangingKeywords">Changing Keywords</a> &middot; <a href="#AlteringBehavior">Altering Behavior</a> &middot; <a href="#SyntaxReference">Syntax Reference</a></div><div class=Topic><a name="Topicstxt"></a><div class=TopicTitle>Topics.txt</div><p>Natural Docs has two files called <code>Topics.txt</code>: one in its Config directory, and one in <a href="running.html#CommandLine">your project directory.</a>&nbsp; These control the topic behavior and keywords Natural Docs uses.</p><p>You should edit the one in your project directory whenever possible.&nbsp; It keeps your changes separate and easier to manage, plus you don&rsquo;t have to reapply them whenever you upgrade.&nbsp; Editing the one in Natural Docs&rsquo; Config directory would be better only if you&rsquo;re using Natural Docs with a lot of projects and would like the changes to apply everywhere.</p></div><div class=Topic><a name="TopicTypesVsKeywords"></a><div class=TopicTitle>Topic Types vs. Keywords</div><p>It&rsquo;s important to understand the difference between topic types and keywords.&nbsp; Topic types have their own indexes and behavior settings.&nbsp; You&rsquo;ll reference them by name when dealing with indexes in the <a href="menu.html">menu file</a> or prototype detection in the <a href="customizinglanguages.html">language file</a>, but not when documenting your code unless you make their names keywords as well.</p><p>You use keywords when documenting your code.&nbsp; There can be many keywords per topic type, and they are completely interchangable.</p><p>Suppose you document a class with the <code>Class</code> keyword and a struct with <code>Struct</code>.&nbsp; They are both keywords for the Class topic type by default, so they will appear in the same index.&nbsp; If you wanted structs to have their own index, you would <a href="#AddingTopicTypes">add a topic type for structs</a> and <a href="#ChangingKeywords">change the <code>Struct</code> keyword to point to it.</a></p></div><div class=Topic><a name="AddingTopicTypes"></a><div class=TopicTitle>Adding Topic Types</div><p>If you want to be able to document something in Natural Docs doesn&rsquo;t handle by default, you want to create your own topic type for it.&nbsp; Let&rsquo;s say you&rsquo;re working on a video game and you want to document all the sound effects because you want to keep track of what each one is for and have an index of them.&nbsp; You&rsquo;d add this to your topics file:</p><pre class=Example>Topic Type: Sound Effect
+   Plural: Sound Effects
+   Keywords:
+      sound
+      sound effect
+</pre><p>Sound effects can now be documented with the <code>sound</code> or <code>sound effect</code> keywords, and they&rsquo;ll get their own index.&nbsp; The <code>Plural</code> line just specifies the plural name of the topic type.&nbsp; It isn&rsquo;t required, but Natural Docs will use it in some places where the plural would sound more natural, like when grouping topics or naming indexes on the menu.</p><p>Here are a couple of other things you may want to add:</p><pre class=Example>Topic Type: Sound Effect
+   Plural: Sound Effects
+   Scope: Always Global
+   Keywords:
+      sound, sounds
+      sound effect, sound effects
+</pre><p>You can set the <a href="documenting/reference.html#KeywordsTopicsAndScope">scope behavior</a> of the topic type.&nbsp; Your options are:</p><table border=0 cellspacing=0 cellpadding=0 class=ScopeTable><tr><td class=ScopeOption>Normal</td><td>Topics stay within the current scope.</td></tr><tr><td class=ScopeOption>Start</td><td>Topics start a new scope for all the topics beneath it, like class topics.</td></tr><tr><td class=ScopeOption>End</td><td>Topics reset the scope back to global for all the topics beneath it.</td></tr><tr><td class=ScopeOption>Always Global</td><td>Topics are defined as global, but do not change the scope for any other topics.</td></tr></table><p>Here we set it to <code>Always Global</code> so that if we document one as part of a class, it will still be global yet will not break the class&rsquo; scope.&nbsp; In other words, we can always link to it with just its name instead of needing something like <code>&lt;Class.Sound&gt;</code>.</p><p>The other thing we did was add plural keywords, which you do by using a comma after an existing keyword.&nbsp; These keywords are used for <a href="documenting/reference.html#ListTopics">list topics</a> so we don&rsquo;t have to document each one individually with the full syntax.</p><p>There are more options, these are just the most important ones.&nbsp; See the <a href="#SyntaxReference">full syntax reference</a> for the rest.</p><a name="Prototypes"></a><div class="SubTopic">Prototypes</div><p>If you&rsquo;d like to collect prototypes for your new topic type, you have to do that by <a href="customizinglanguages.html#Prototypes">editing <code>Languages.txt</code></a>.</p></div><div class=Topic><a name="ChangingKeywords"></a><div class=TopicTitle>Changing Keywords</div><a name="AddingAndChanging"></a><div class="SubTopic First">Adding and Changing</div><p>If you&rsquo;re <a href="#AddingTopicTypes">defining your own topic type</a> or editing the main topics file, you simply add to the keywords list:</p><pre class=Example>Topic Type: Sound Effect
+   Keywords:
+      sound, sounds
+      sound effect, sound effects
+</pre><p>It doesn&rsquo;t matter if the keyword was previously defined for a different topic type.&nbsp; Just define it again and the definition will change.</p><p>If you want to add keywords to one of the main topic types from the project file, use <code>Alter Topic Type</code> instead:</p><pre class=Example>Alter Topic Type: General
+   Keywords:
+      note
+      notes
+</pre><p>Natural Docs will keep a list of the main file&rsquo;s topic types in your project file so that you can do this easily.</p><a name="Ignoring"></a><div class="SubTopic">Ignoring</div><p>Sometimes a keyword just gets in the way.&nbsp; It&rsquo;s too common in your comments and Natural Docs keeps accidentally picking them up as topics when that isn&rsquo;t what you wanted.&nbsp; You can get rid of keywords completely by either deleting them from the main file or putting this in your project file:</p><pre class=Example>Ignore Keywords:
+   about
+   title
+</pre><p>If you only have a few, you can use this syntax as well:</p><pre class=Example>Ignore Keywords: note, notes, title
+</pre></div><div class=Topic><a name="AlteringBehavior"></a><div class=TopicTitle>Altering Behavior</div><p>You can change the behavior of any topic type defined in the main file via your project file.&nbsp; Just use <code>Alter Topic Type</code> and redefine any property.</p><pre class=Example>Alter Topic Type: Constant
+   Scope: Always Global
+</pre><p>Natural Docs will keep a list of the main file&rsquo;s topic types in your project file so you can do this easily.&nbsp; See the <a href="#SyntaxReference">syntax reference</a> below for a full list of your options.</p></div><div class=Topic><a name="SyntaxReference"></a><div class=TopicTitle>Syntax Reference</div><pre class=Example>Ignore Keywords: <i>[keyword]</i>, <i>[keyword]</i> ...
+   <i>[keyword]</i>
+   <i>[keyword]</i>, <i>[keyword]</i>
+   ...
+</pre><p>Ignores the keywords so that they&rsquo;re not recognized as Natural Docs topics anymore.&nbsp; Can be specified as a list on the same line and/or following like a normal Keywords section.</p><pre class=Example>Topic Type: <i>[name]</i>
+Alter Topic Type: <i>[name]</i>
+</pre><p>Creates a new topic type or alters an existing one.&nbsp; The name can only contain letters, numbers, spaces, and these characters: <code>. - &lsquo; /</code>.&nbsp; It isn&rsquo;t case sensitive, although the original case is remembered for presentation.</p><p>There are a number of default types that must be defined in the main file, but they will be listed there since it may change between versions.&nbsp; The default types can have their keywords or behaviors changed, though, either by editing the default file or by overriding them in the user file.</p><a name="Properties"></a><div class="SubTopic">Properties</div><pre class=Example>Plural: <i>[name]</i>
+</pre><p>Specifies the plural name of the topic type.&nbsp; Defaults to the singular name.&nbsp; Has the same restrictions as the topic type name.</p><pre class=Example>Index: <i>[yes|no]</i>
+</pre><p>Whether the topic type gets an index.&nbsp; Defaults to yes.</p><pre class=Example>Scope: <i>[normal|start|end|always global]</i>
+</pre><p>How the topic affects scope.&nbsp; Defaults to normal.</p><table border=0 cellspacing=0 cellpadding=0 class=ScopeTable><tr><td class=ScopeOption>Normal</td><td>Topics stay within the current scope.</td></tr><tr><td class=ScopeOption>Start</td><td>Topics start a new scope for all the topics beneath it, like class topics.</td></tr><tr><td class=ScopeOption>End</td><td>Topics reset the scope back to global for all the topics beneath it.</td></tr><tr><td class=ScopeOption>Always Global</td><td>Topics are defined as global, but do not change the scope for any other topics.</td></tr></table><pre class=Example>Class Hierarchy: <i>[yes|no]</i>
+</pre><p>Whether the topic is part of the class hierarchy.&nbsp; Defaults to no.</p><pre class=Example>Page Title if First: <i>[yes|no]</i>
+</pre><p>Whether the title of this topic becomes the page title if it is the first topic in a file.&nbsp; Defaults to no.</p><pre class=Example>Break Lists: <i>[yes|no]</i>
+</pre><p>Whether <a href="documenting/reference.html#ListTopics">list topics</a> should be broken into individual topics in the output.&nbsp; Defaults to no.</p><pre class=Example>Can Group With: <i>[topic type]</i>, <i>[topic type]</i>, ...
+</pre><p>Lists the topic types that can be grouped with this one in the output.&nbsp; If two or more topic types often appear together, like Functions and Properties, this will allow them to be grouped together under one heading if it would cause too many groups otherwise.</p><pre class=Example>Keywords:
+   <i>[keyword]</i>
+   <i>[keyword]</i>, <i>[plural keyword]</i>
+   ...
+</pre><p>A list of the topic type&rsquo;s keywords.&nbsp; Each line after the heading is the keyword and optionally its plural form.&nbsp; This continues until the next line in &ldquo;<code>keyword: value</code>&rdquo; format.</p><ul><li>Keywords can only have letters, numbers, and spaces.&nbsp; No punctuation or symbols are allowed.</li><li>Keywords are not case sensitive.</li><li>Subsequent keyword sections add to the list.&nbsp; They don&rsquo;t replace it.</li><li>Keywords can be redefined by appearing in later keyword sections.</li></ul></div></td></tr><tr><td></td><td class=SideMenuBottom><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td class=SideMenuBottomLeft><img src="images/menu/bottomleft.png" width=18 height=19></td><td class=SideMenuBottomRight><img src="images/menu/bottomright.png" width=18 height=19></td></tr></table></td><td class=BodyBottom>Copyright &copy; 2003-2008 Greg Valure</td></tr></table><script language=JavaScript><!--
+ClosingBrowserTags();// --></script></body></html>

data/template/assets/naturaldocs/NaturalDocs/Help/documenting.html ADDED

@@ -0,0 +1,58 @@
+<html><head><title>Documenting Your Code - Natural Docs</title><link rel=stylesheet type="text/css" href="styles.css"><link rel=stylesheet type="text/css" href="examples.css"><style type="text/css"><!--
+    #ReferenceTable {
+        width: 100%;
+        }
+    #ReferenceTable #LeftSide {
+        padding-right: 4ex;
+        width: 40%;
+        }
+    #ReferenceTable #RightSide {
+        width: 60%;
+        }
+    #LeftSide a:link,
+    #LeftSide a:hover,
+    #LeftSide a:visited {
+        color: #000000;
+        }
+    #LeftSide .TopicTitle a:hover,
+    #LeftSide .TopicTitle a:active {
+        text-decoration: none;
+        }
+    #RightSide .Example {
+        margin-left: 0;
+        margin-right: 0;
+        }
+--></style><script language=JavaScript src="javascript/PNGHandling.js"></script><script language=JavaScript src="javascript/BrowserStyles.js"></script></head><body marginwidth=0 marginheight=0 leftmargin=0 topmargin=0><script language=JavaScript><!--
+OpeningBrowserTags();// --></script>
+<!-- saved from url=(0026)http://www.naturaldocs.org -->
+<table width=100% border=0 cellspacing=0 cellpadding=0><tr><td colspan=3 class=Header><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td><img src="images/header/leftside.png" width=30 height=75><a href="index.html"><img src="images/header/logo.png" width=524 height=75 alt="Natural Docs"></a></td><td align=right><img src="images/header/rightside.png" width=30 height=75></td></tr></table></td></tr><tr><td><img src="images/header/overleftmargin.png" width=10 height=6></td><td class=SideMenuTop><img src="images/header/overmenu.png" width=14 height=6></td><td class=BodyTop><img src="images/header/overbody.png" width=24 height=6></td></tr><tr><td></td><td class=SideMenu nowrap><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/about.png" width=52 height=13 alt="About"></div><div class=SideMenuBody><a href="languages.html" class=SideMenuEntry>Language Support</a><a href="output.html" class=SideMenuEntry>Output Formats</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/using.png" width=45 height=13 alt="Using"></div><div class=SideMenuBody><span class=SideMenuEntry id=SelectedSideMenuEntry>Documenting<br>Your Code</span><a href="keywords.html" class=SideMenuEntry>Keywords</a><a href="running.html" class=SideMenuEntry>Running</a><a href="troubleshooting.html" class=SideMenuEntry>Troubleshooting</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/customizing.png" width=96 height=13 alt="Customizing"></div><div class=SideMenuBody><a href="menu.html" class=SideMenuEntry>Organizing the Menu</a><a href="styles.html" class=SideMenuEntry>CSS Styles</a><a href="customizingtopics.html" class=SideMenuEntry>Topics and Keywords</a><a href="customizinglanguages.html" class=SideMenuEntry>Languages, Indexes,<br>and Prototypes</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/community.png" width=86 height=13 alt="Community"></div><div class=SideMenuBody><a href="http://www.naturaldocs.org/" class=SideMenuEntry>Web Site</a><a href="http://www.naturaldocs.org/mailinglist.html" class=SideMenuEntry>Mailing Lists</a><a href="http://www.naturaldocs.org/messageboards.html" class=SideMenuEntry>Message Boards</a><a href="http://www.naturaldocs.org/bugs.html" class=SideMenuEntry>Bugs and<br>Feature Requests</a></div></div></td><td class=Body width=100%><div class=PageTitle>Documenting Your Code</div><div class=Topic><table id=ReferenceTable border=0 cellspacing=0 cellpadding=0><tr><td id=LeftSide><div class=Topic><div class=TopicTitle><a href="documenting/walkthrough.html">Walkthrough</a></div><ul><li><a href="documenting/walkthrough.html#OurFirstFunction">Our First Function</a></i><li><a href="documenting/walkthrough.html#ClassesAndScope">Classes and Scope</a></i><li><a href="documenting/walkthrough.html#MoreFormatting">More Formatting</a></i><li><a href="documenting/walkthrough.html#MoreOnLinking">More on Linking</a></i><li><a href="documenting/walkthrough.html#ExtraDocumentation">Extra Documentation</a></i><li><a href="documenting/walkthrough.html#AbbreviatedSyntax">Abbreviated Syntax</a></i></ul></div><div class=Topic><div class=TopicTitle><a href="documenting/reference.html">Reference</a></div><ul><li><a href="documenting/reference.html#Comments">Comments</a></i><li><a href="documenting/reference.html#TextFiles">Text Files</a></i><li><a href="documenting/reference.html#KeywordsTopicsAndScope">Keywords, Topics, and Scope</a></i><li><a href="documenting/reference.html#Linking">Linking</a></i><li><a href="documenting/reference.html#FormattingAndLayout">Formatting and Layout</a></i><li><a href="documenting/reference.html#PageTitles">Page Titles</a></i><li><a href="documenting/reference.html#Summaries">Summaries</a></i><li><a href="documenting/reference.html#JavadocCompatibility">Javadoc Compatibility</a></i></ul></div></td><td id=RightSide><p>Here&rsquo;s a quick example of how to document your code for Natural Docs.&nbsp; If you&rsquo;re a new user, we have <a href="documenting/walkthrough.html">a walkthrough</a> to get you started.&nbsp; Otherwise, visit <a href="documenting/reference.html">the reference</a> for the full details.</p><pre class=Example>/*
+   Function: Multiply
+   Multiplies two integers.
+   Parameters:
+      x - The first integer.
+      y - The second integer.
+   Returns:
+      The two integers multiplied together.
+   See Also:
+      &lt;Divide&gt;
+*/
+int Multiply (int x, int y)
+   {  return x * y;  };</pre></td></tr></table></div></td></tr><tr><td></td><td class=SideMenuBottom><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td class=SideMenuBottomLeft><img src="images/menu/bottomleft.png" width=18 height=19></td><td class=SideMenuBottomRight><img src="images/menu/bottomright.png" width=18 height=19></td></tr></table></td><td class=BodyBottom>Copyright &copy; 2003-2008 Greg Valure</td></tr></table><script language=JavaScript><!--
+ClosingBrowserTags();// --></script></body></html>

data/template/assets/naturaldocs/NaturalDocs/Help/documenting/reference.html ADDED

@@ -0,0 +1,146 @@
+<html><head><title>Documenting Your Code: Reference - Natural Docs</title><link rel=stylesheet type="text/css" href="../styles.css"><link rel=stylesheet type="text/css" href="../examples.css"><style type="text/css"><!--
+        .KeywordList                        { margin: 1em 5ex }
+        .KeywordList td                { padding-bottom: 1em }
+                .KeywordListKeyword                {  font-weight: bold; white-space: nowrap  }
+                .KeywordListDescription                {  padding-left: 5ex  }
+                .KeywordListSynonyms                {  font-weight: normal; font-size: 8pt; font-style: italic }
+                .KeywordListSynonyms a:link,
+                .KeywordListSynonyms a:visited,
+                .KeywordListSynonyms a:hover                { color: #808080 }
+--></style><script language=JavaScript src="../javascript/PNGHandling.js"></script><script language=JavaScript src="../javascript/BrowserStyles.js"></script><script language=JavaScript src="../example/NaturalDocs.js"></script></head><body marginwidth=0 marginheight=0 leftmargin=0 topmargin=0><script language=JavaScript><!--
+OpeningBrowserTags();// --></script>
+<!-- saved from url=(0026)http://www.naturaldocs.org -->
+<table width=100% border=0 cellspacing=0 cellpadding=0><tr><td colspan=3 class=Header><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td><img src="../images/header/leftside.png" width=30 height=75><a href="../index.html"><img src="../images/header/logo.png" width=524 height=75 alt="Natural Docs"></a></td><td align=right><img src="../images/header/rightside.png" width=30 height=75></td></tr></table></td></tr><tr><td><img src="../images/header/overleftmargin.png" width=10 height=6></td><td class=SideMenuTop><img src="../images/header/overmenu.png" width=14 height=6></td><td class=BodyTop><img src="../images/header/overbody.png" width=24 height=6></td></tr><tr><td></td><td class=SideMenu nowrap><div class=SideMenuSection><div class=SideMenuTitle><img src="../images/menu/about.png" width=52 height=13 alt="About"></div><div class=SideMenuBody><a href="../languages.html" class=SideMenuEntry>Language Support</a><a href="../output.html" class=SideMenuEntry>Output Formats</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="../images/menu/using.png" width=45 height=13 alt="Using"></div><div class=SideMenuBody><a href="../documenting.html" class=SideMenuEntry id=SelectedSideMenuEntry>Documenting<br>Your Code</a><a href="../keywords.html" class=SideMenuEntry>Keywords</a><a href="../running.html" class=SideMenuEntry>Running</a><a href="../troubleshooting.html" class=SideMenuEntry>Troubleshooting</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="../images/menu/customizing.png" width=96 height=13 alt="Customizing"></div><div class=SideMenuBody><a href="../menu.html" class=SideMenuEntry>Organizing the Menu</a><a href="../styles.html" class=SideMenuEntry>CSS Styles</a><a href="../customizingtopics.html" class=SideMenuEntry>Topics and Keywords</a><a href="../customizinglanguages.html" class=SideMenuEntry>Languages, Indexes,<br>and Prototypes</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="../images/menu/community.png" width=86 height=13 alt="Community"></div><div class=SideMenuBody><a href="http://www.naturaldocs.org/" class=SideMenuEntry>Web Site</a><a href="http://www.naturaldocs.org/mailinglist.html" class=SideMenuEntry>Mailing Lists</a><a href="http://www.naturaldocs.org/messageboards.html" class=SideMenuEntry>Message Boards</a><a href="http://www.naturaldocs.org/bugs.html" class=SideMenuEntry>Bugs and<br>Feature Requests</a></div></div></td><td class=Body width=100%><div class=PageTitle>Documenting Your Code</div><div class=TOC><a href="#Comments">Comments</a> &middot; <a href="#TextFiles">Text Files</a> &middot; <a href="#KeywordsTopicsAndScope">Keywords, Topics, and Scope</a> &middot; <a href="#Linking">Linking</a><br><a href="#FormattingAndLayout">Formatting and Layout</a> &middot; <a href="#PageTitles">Page Titles</a> &middot; <a href="#Summaries">Summaries</a> &middot; <a href="#JavadocCompatibility">Javadoc Compatibility</a></div><div class=CToolTip id="ttAdd"><div class=CFunction><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>int Add (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Adds two integers.</div></div><div class=CToolTip id="ttSubtract"><div class=CFunction><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>int Subtract (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Subtracts two integers.</div></div><div class=CToolTip id="ttMultiply"><div class=CFunction><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>int Multiply (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Multiplies two integers.</div></div><div class=CToolTip id="ttDivide"><div class=CFunction><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>int Divide (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Divides two integers.</div></div><div class=CToolTip id="ttIsEqual"><div class=CFunction><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>bool IsEqual (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Returns whether two integers are equal.</div></div><div class=Topic><a name="Comments"></a><div class=TopicTitle>Comments</div><p>There is no special comment style for Natural Docs.&nbsp; You just embed Natural Docs topics into regular comments, and it&rsquo;s pretty tolerant as far as style goes.&nbsp; You can use block comments or string together line comments.&nbsp; The only requirement is that the comments are not on the same line as code.</p><pre class=Example>/* Function: Multiply
+   Multiplies two integers and returns the result. */
+// Function: Multiply
+// Multiplies two integers and returns the result.
+</pre><p>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.&nbsp; If a line is completely blank, it&rsquo;s considered the end of the comment and thus the end of the Natural Docs topic.</p><a name="BoxesAndHorizontalLines"></a><div class="SubTopic">Boxes and Horizontal Lines</div><p>Natural Docs can also handle comment boxes and horizontal lines.&nbsp; It doesn&rsquo;t matter what symbols they use.&nbsp; The boxes don&rsquo;t need to be closed on the right side, and they can have different symbols for the edges and corners.</p><pre class=Example>/*
+ * 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.
+//
+//////////////////////////////////////////////////////////////
+</pre><a name="JavadocStyle"></a><div class="SubTopic">Javadoc Style</div><p>If you have <a href="../languages.html">full language support</a>, you can also use Javadoc-style comments to write Natural Docs documentation.&nbsp; To do this you repeat the last symbol on the first line of the comment once.&nbsp; The comment must appear directly above what it&rsquo;s documenting, and you can omit the topic line if you want (the &ldquo;<code>Function: Multiply</code>&rdquo; part.)</p><pre class=Example>/**
+ * Multiplies two integers and returns the result.
+ */
+///
+// Multiplies two integers together and returns the result.
+</pre><p>If you omit the topic line and include any Javadoc tags in the comment, like <code>@param</code>, the entire comment will be treated as Javadoc and can only use Javadoc formatting.&nbsp; Otherwise it&rsquo;s treated as a Natural Docs comment and you can use all the formatting options described on this page.&nbsp; You can have both styles in the same source file, but not in the same comment.</p><a name="PerlPOD"></a><div class="SubTopic">Perl POD</div><p>Perl users can also use POD to do block comments.</p><pre class=Example>=begin nd
+Function: Multiply
+Multiplies two integers and returns the result.
+=cut
+</pre><p>You can also use <code>NaturalDocs</code> or <code>Natural Docs</code> in place of <code>ND</code>.&nbsp; None of them are case sensitive.&nbsp; If for some reason you want to go back to POD documentation instead of using <code>=cut</code>, you can write <code>=end nd</code>.</p><p>There&rsquo;s a second form of just <code>=nd</code> which is offered as a convenience.&nbsp; However, it is <b>not valid POD</b>.&nbsp; Perl will skip over it and execute fine, but POD parsers will give errors and possibly include the unformatted text in the output.&nbsp; Use the longer, valid form unless you know for certain that no one will ever try to run POD on your code.</p><pre class=Example>=nd
+Function: Multiply
+Multiplies two integers and returns the result.
+=cut
+</pre></div><div class=Topic><a name="TextFiles"></a><div class=TopicTitle>Text Files</div><p>Documentation can also be included in text files.&nbsp; Any file with a .txt extension appearing in the source tree and starting with a topic line will included in the documentation.&nbsp; 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.&nbsp; The only difference is you don&rsquo;t need comment symbols.</p><p>Remember that the topic line is required to be the first line of content.&nbsp; If the first non-blank line is not in the &ldquo;<code>Function: Multiply</code>&rdquo; format the file will be ignored.&nbsp; An easy way to do this is to use the <code>Title</code> keyword, although all of <a href="../keywords.html">the other ones</a> will work as well.</p><pre class=Example>Title: License
+This project is licensed under the GPL.
+</pre><p>This method is convenient for documenting file formats, configuration settings, the general program architecture, or anything else that isn&rsquo;t directly tied to a source file.</p></div><div class=Topic><a name="KeywordsTopicsAndScope"></a><div class=TopicTitle>Keywords, Topics, and Scope</div><p>A topic in Natural Docs starts with a topic line in the format <code>&ldquo;keyword: name&rdquo;</code>.&nbsp; You can have multiple topics per comment as long as you separate them with a blank line.&nbsp; The keywords aren&rsquo;t case sensitive.</p><p>The list of keywords is pretty predictable: Function, Class, Variable, etc.&nbsp; Just use what you&rsquo;re documenting.&nbsp; There are many synonyms as well, so you can use keywords like Func, Procedure, Proc, Method and Constructor.&nbsp; Look at the <a href="../keywords.html">full list of keywords</a> to see everything that&rsquo;s available.</p><p>The <a href="../keywords.html">list of keywords</a> is separated into topic types.&nbsp; Each type gets its own index, and which specific keyword you use doesn&rsquo;t matter.&nbsp; Some also have scoping rules or other behavior as noted.</p><a name="Scope"></a><div class="SubTopic">Scope</div><p>Like the code it&rsquo;s documenting, Natural Docs topics have scope.&nbsp; This mostly has to do with <a href="#Linking">linking</a>: if you&rsquo;re in a class you can link to its members by their name alone, but if you&rsquo;re not, you have to use a notation like <code>class.member</code> or <code>class::member</code>.</p><p>If you have <a href="../languages.html">full language support</a> and are documenting something that appears in the code, the scope will be handled automatically.&nbsp; If you&rsquo;re using text files, have basic language support, or are including a topic that doesn&rsquo;t correspond to something in the code, scoping follows these rules:</p><ul><li>Everything after a class topic (or <a href="../keywords.html">anything that says &ldquo;Starts Scope&rdquo;</a>) is part of that class.</li><li>Everything after a section topic (or <a href="../keywords.html">anything that says &ldquo;Ends Scope&rdquo;</a>) is global again.</li><li>File topics (or <a href="../keywords.html">anything that says &ldquo;Always Global&rdquo;</a>) are global but do not change the scope for what follows.</li><p></ul></p><a name="ListTopics"></a><div class="SubTopic">List Topics</div><p>If you looked at the list, you saw that most of the keywords have plural forms.&nbsp; That&rsquo;s for list topics, which let you document many small things without using the full syntax.&nbsp; Anything that appears in <a href="#DefinitionLists">definition lists</a> within that topic will be treated as if it had its own topic.&nbsp; It will appear in the indexes and be linkable, just like normal topics.</p><p>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.</p></div><div class=Topic><a name="Linking"></a><div class=TopicTitle>Linking</div><p>Linking is the one place where Natural Docs has some negative effect on the readability of the comments.&nbsp; 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 &ldquo;is&rdquo; or &ldquo;on&rdquo;.&nbsp; However, the Natural Docs syntax is still as minimal as possible.&nbsp; Simply surround any topic you want to link to with angle brackets.&nbsp; Natural Docs will keep track off all the topics and where they are defined, so you don&rsquo;t need to use HTML-like syntax or remember what file anything is in.&nbsp; Also, if the link can&rsquo;t be resolved to anything, Natural Docs leaves the angle brackets in the output so if something wasn&rsquo;t intended to be a link (such as <code>#include &lt;somefile.h&gt;</code>) it won&rsquo;t be mangled.</p><pre class=Example>Let's link to function &lt;Multiply&gt;.
+</pre><div class=NDContent><p class=CParagraph>Let&rsquo;s link to function <a href="#Example_Class.Multiply" class=LFunction id=link632 onMouseOver="ShowTip(event, 'ttMultiply', 'link632')" onMouseOut="HideTip('ttMultiply')">Multiply</a>.</p></div><p>Links and topic names are case sensitive, regardless of whether the language is or not.</p><p>When linking to functions, it doesn&rsquo;t matter if you include empty parenthesis or not.&nbsp; Both <code>&lt;Function&gt;</code> and <code>&lt;Function()&gt;</code> will work.&nbsp; However, if you documented the function with parameters as part of the name, you will need to include those parameters whenever linking to it.&nbsp; It is recommended that you only include parameters in the topic name if you need to distinguish between two functions with the same name.</p><p>If the topic has a <a href="#Summaries">summary sentence</a>, hovering over the link will give it to you as a tooltip.&nbsp; If the topic has a prototype, that will be included as well.&nbsp; You can try it above.</p><div class="SubTopic">Scope</div><p>If a topic is <a href="#Scope">considered part of a class</a>, they can be linked to using any of the three most common class/member notations:&nbsp; <code>class.member</code>, <code>class::member</code>, and <code>class-&gt;member</code>.&nbsp; Natural Docs will not be confused by <code>&lt;class-&gt;member&gt;</code>.&nbsp; Like in the language itself, if the topic you&rsquo;re writing is in that class&rsquo; scope you can link to it simply as <code>&lt;member&gt;</code>.</p><p>If you have multi-level classes and packages, links can be relative as well.&nbsp; So if you&rsquo;re in <code>Project::UI::Window::Base</code> and you want to link to <code>Project::UI::Button::Base</code>, just using <code>&lt;Button::Base&gt;</code> will work.</p><a name="PluralsAndPossessives"></a><div class="SubTopic">Plurals and Possessives</div><p>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.&nbsp; In other words, you don&rsquo;t have to use awkward syntax like <code>&lt;Object&gt;s</code>, although that&rsquo;s supported as well.&nbsp; You can simply write <code>&lt;Objects&gt;</code> and it will link to the symbol <code>Object</code> just fine.&nbsp; It can handle any plural and/or possessive form you can throw at it.&nbsp; I&rsquo;m not kidding: <code>Foxes</code>, <code>Fox&rsquo;s</code>, <code>Foxes&rsquo;</code>, <code>Children</code>, <code>Mice</code>, <code>Alumni</code>, <code>Indices</code>, <code>Amoebae</code>, <code>Teeth</code>, just try to trip it up.</p><a name="URLsAndEMail"></a><div class="SubTopic">URLs and E-Mail</div><p>You can also link to URLs and e-mail addresses.&nbsp; It will detect them automatically, but you can also put them in angle brackets if you like.</p><pre class=Example>Visit &lt;http://www.website.com&gt; or send messages to
+email@address.com.
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><p class=CParagraph>Visit <a href="#" onClick="return false;" class=LURL>http://www.website.com</a> or send messages to <a href="#" onclick="location.href='mai' + 'lto:' + 'em' + 'ail' + '@' + 'addre' + 'ss.com'; return false;" class="LEMail">em<span style="display: none;">.nosp@m.</span>ail<span>@</span>addre<span style="display: none;">.nosp@m.</span>ss.com</a>.</p></div></div></div></div><p>E-mail addresses are protected in a way that should avoid spam crawlers.&nbsp; Although the link above looks and acts like a regular link (try it) the HTML code actually looks like this:</p><pre class=Example>&lt;a href="#"
+ onClick="location.href='mai' + 'lto:' + 'em' + 'ail' + '@'
+          + 'addre' + 'ss.com'; return false;"&gt;
+    em&lt;span style="display: none"&gt;.nosp@m.&lt;/span&gt;ail
+    &lt;span&gt;@&lt;/span&gt;
+    addre&lt;span style="display: none"&gt;.nosp@m.&lt;/span&gt;ss.com
+&lt;/a&gt;
+</pre></div><div class=Topic><a name="FormattingAndLayout"></a><div class=TopicTitle>Formatting and Layout</div><p>You can apply additional formatting and layout to your Natural Docs content, all in ways that will appear very natural in the source code.</p><a name="Paragraphs"></a><div class="SubTopic">Paragraphs</div><p>You can break paragraphs by leaving blank lines between them.&nbsp; So we have this in our content:</p><pre class=Example>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.
+</pre><p>and we get this in our output:</p><div class=NDContent><div class=CBody><div class=CFunction><div class=CTopic><p class=CParagraph>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.</p><p class=CParagraph>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.</p></div></div></div></div><a name="BoldAndUnderline"></a><div class="SubTopic">Bold and Underline</div><p>You can apply bold to a stretch of text by surrounding it with asterisks.&nbsp; You can apply underlining by surrounding it with underscores instead.&nbsp; With underlining, it doesn&rsquo;t matter if you use an underscore for every space between words or not; they&rsquo;ll be converted to spaces if you do.</p><pre class=Example>Some *bold text* and some _underlined text_
+and yet _more_underlined_text_.
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><p class=CParagraph>Some <b>bold text</b> and some <u>underlined text</u> and yet <u>more underlined text</u>.</p></div></div></div></div><a name="Headings"></a><div class="SubTopic">Headings</div><p>You can add headings to your output just by ending a line with a colon and having a blank line above it.</p><pre class=Example>Some text before the heading.
+Heading:
+Some text under the heading.
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><p class=CParagraph>Some text before the heading.</p><h4 class=CHeading>Heading</h4><p class=CParagraph>Some text under the heading.</p></div></div></div></div><p>You <u>must</u> have a blank line above the heading or it will not work.&nbsp; You can skip the blank after it but not before.</p><a name="BulletLists"></a><div class="SubTopic">Bullet Lists</div><p>You can add bullet lists by starting a line with a dash, an asterisk, an o, or a plus.&nbsp; Bullets can have blank lines between them if you want, and subsequent lines don&rsquo;t have to be indented.&nbsp; You end a list by skipping a line and doing something else.</p><pre class=Example>- 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.
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><ul class=CBulletList><li>Bullet one.</li><li>Bullet two.&nbsp; Bullet two continued.</li><li>Bullet three.</li></ul><p class=CParagraph>Some text after the bullet list.</p><ul class=CBulletList><li>Spaced bullet one.</li><li>Spaced bullet two.&nbsp; Spaced bullet two continued.</li><li>Spaced bullet three.</li></ul><p class=CParagraph>Some text after the spaced bullet list.</p></div></div></div></div><a name="DefinitionLists"></a><div class="SubTopic">Definition Lists</div><p>You can add a definition list by using the format below, specifically &ldquo;text space dash space text&rdquo;.&nbsp; Like bullet lists, you can have blank lines between them if you want, subsequent lines don&rsquo;t have to be indented, and you end the list by skipping a line and doing something else.</p><pre class=Example>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.
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><table border=0 cellspacing=0 cellpadding=0 class=CDescriptionList><tr><td class=CDLEntry>First</td><td class=CDLDescription>This is the first item.</td></tr><tr><td class=CDLEntry>Second</td><td class=CDLDescription>This is the second item.&nbsp; This is more of the second item.</td></tr><tr><td class=CDLEntry>Third</td><td class=CDLDescription>This is the third item.&nbsp; This is more of the third item.</td></tr></table><p class=CParagraph>Some text after the definition list.</p></div></div></div></div><p>Remember that with definition lists, if you&rsquo;re using the plural form of the keywords each entry can be linked to as if it had its own topic.</p><a name="CodeAndTextDiagrams"></a><div class="SubTopic">Code and Text Diagrams</div><p>You can add example code or text diagrams by starting each line with <code>&gt;</code>, <code>|</code>, or <code>:</code>.&nbsp; If you have a vertical line or text box with the comment, you must separate these symbols from it with a space.</p><pre class=Example>: a = b + c;
+&gt;   +-----+     +-----+
+&gt;   |  A  | --> |  B  |
+&gt;   +-----+     +-----+
+&gt;                  |
+&gt;               +-----+
+&gt;               |  C  |
+&gt;               +-----+
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><pre class=CCode>a = b + c;</pre><pre class=CCode>+-----+     +-----+<br>|  A  | --> |  B  |<br>+-----+     +-----+<br>               |<br>            +-----+<br>            |  C  |<br>            +-----+</pre></div></div></div></div><p>For long stretches, this may be too tedious.&nbsp; You can start a code section by placing <code>(start code)</code> or just <code>(code)</code> alone on a line.&nbsp; You end it with either <code>(end code)</code> or just <code>(end)</code>.&nbsp; You can&rsquo;t put any other content on these lines.</p><pre class=Example>(start code)
+if (x == 0) {
+   DoSomething();
+}
+return x;
+(end)
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><pre class=CCode>if (x == 0) {<br>   DoSomething();<br>}<br><br>return x;</pre></div></div></div></div><p>You can also use <code>example</code>, <code>diagram</code>, or <code>table</code> instead of <code>code</code>.&nbsp; Just use whatever&rsquo;s appropriate.&nbsp; Always flexible, it will accept <code>begin</code> for <code>start</code> and it will accept <code>finish</code> or <code>done</code> for <code>end</code> so you don&rsquo;t have to remember the exact word.</p><a name="Images"></a><div class="SubTopic">Images</div><p>You can include images in your documentation by writing &ldquo;<code>(see filename)</code>&rdquo;.&nbsp; If you put it alone on a line it will be embedded in place.</p><pre class=Example>This is the first paragraph.
+(see logo.gif)
+This is the second paragraph.
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><p class=CParagraph>This is the first paragraph.</p><img src="../images/logo.gif" width="268" height="61"><p class=CParagraph>This is the second paragraph.</p></div></div></div></div><p>If it&rsquo;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.</p><pre class=Example>This is the first paragraph (see logo.gif)  This is
+more of the first paragraph.
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><p class=CParagraph>This is the first paragraph <a href="#Image1" class=CImageLink>(see logo)</a>&nbsp; This is more of the first paragraph.</p><div class=CImage><a name="Image1"></a><div class=CImageCaption>logo</div><img src="../images/logo.gif" width="268" height="61"></div></div></div></div></div><p>The image file names are relative to the source file the comment appears in or any directories specified with the <a href="../running.html#CommandLine"><code>-img</code> command line option</a>.&nbsp; You can use relative paths like <code>(see images/logo.gif)</code> and <code>(see ../images/logo.gif)</code>, but you cannot use absolute paths, URLs, or specify a file that&rsquo;s not in a folder included by <a href="../running.html#CommandLine"><code>-i</code></a> or <a href="../running.html#CommandLine"><code>-img</code></a>.</p><p>Natural Docs supports gif, jpg, jpeg, png, and bmp files.</p></div><div class=Topic><a name="PageTitles"></a><div class=TopicTitle>Page Titles</div><p>Natural Docs automatically determines the page title as follows:</p><ul><li>If there&rsquo;s only one topic in the file, that topic&rsquo;s title becomes the page title.</li><li>Otherwise, if the first topic in the file is a class, section, or file, that topic&rsquo;s title becomes the page title.</li><li>Otherwise, the file name becomes the page title.</li><p></ul></p><p>This should be enough for most people.&nbsp; However, if you don&rsquo;t like the page title Natural Docs has chosen for you, add a &ldquo;<code>Title: [name]</code>&rdquo; comment to the top of the file to override it.&nbsp; <code>Title</code> is a synonym of Section, so that will satisfy the second rule and make it the page title.</p></div><div class=Topic><a name="Summaries"></a><div class=TopicTitle>Summaries</div><p>Summaries are automatically generated for every file, class, and section.&nbsp; You don&rsquo;t have to do anything special to get them.</p><p>There are two things you may want to keep in mind when documenting your code so that the summaries are nicer.&nbsp; The first is that they use the first sentence in the topic as the description, so long as it&rsquo;s plain text and not something like a bullet list.&nbsp; It will also appear in the tooltip whenever that topic is linked to.</p><p>The second is that you may want to manually add group topics to divide long lists and make the summaries easier to navigate.&nbsp; Natural Docs will automatically group them by type if you do not, but sometimes you want to be more specific.&nbsp; You don&rsquo;t need to provide a description, just adding a &ldquo;<code>Group: [name]</code>&rdquo; comment is sufficient.&nbsp; Note that once you manually add a group automatic grouping is completely turned off for that class.</p><p>Here&rsquo;s an example summary.&nbsp; Note that as before, when you hover over a link, you&rsquo;ll get the prototype and summary line as a tooltip.</p><div class=NDSummary><div class=Summary><div class=STitle>Summary</div><div class=SBorder><table border=0 cellspacing=0 cellpadding=0 class=STable><tr><td class=SEntrySize><div class=SMain><div class=SEntry><a href="#Example_Class" >Example Class</a></div></div></td><td class=SDescriptionSize><div class=SMain><div class=SDescription>A example class that does arithmetic with functions for people scared of operators.</div></div></td></tr><tr><td><div class=SGroup><div class=SEntry><div class=SIndent1><a href="#Example_Class.Arithmetic_Functions" >Arithmetic Functions</a></div></div></div></td><td><div class=SGroup><div class=SDescription><div class=SIndent1></div></div></div></td></tr><tr class=SMarked><td><div class=SFunction><div class=SEntry><div class=SIndent2><a href="#Example_Class.Add" id=link1 onMouseOver="ShowTip(event, 'ttAdd', 'link1')" onMouseOut="HideTip('ttAdd')">Add</a></div></div></div></td><td><div class=SFunction><div class=SDescription><div class=SIndent2>Adds two integers.</div></div></div></td></tr><tr><td><div class=SFunction><div class=SEntry><div class=SIndent2><a href="#Example_Class.Subtract" id=link2 onMouseOver="ShowTip(event, 'ttSubtract', 'link2')" onMouseOut="HideTip('ttSubtract')">Subtract</a></div></div></div></td><td><div class=SFunction><div class=SDescription><div class=SIndent2>Subtracts two integers.</div></div></div></td></tr><tr class=SMarked><td><div class=SFunction><div class=SEntry><div class=SIndent2><a href="#Example_Class.Multiply" id=link3 onMouseOver="ShowTip(event, 'ttMultiply', 'link3')" onMouseOut="HideTip('ttMultiply')">Multiply</a></div></div></div></td><td><div class=SFunction><div class=SDescription><div class=SIndent2>Multiplies two integers.</div></div></div></td></tr><tr><td><div class=SFunction><div class=SEntry><div class=SIndent2><a href="#Example_Class.Divide" id=link4 onMouseOver="ShowTip(event, 'ttDivide', 'link4')" onMouseOut="HideTip('ttDivide')">Divide</a></div></div></div></td><td><div class=SFunction><div class=SDescription><div class=SIndent2>Divides two integers.</div></div></div></td></tr><tr><td><div class=SGroup><div class=SEntry><div class=SIndent1><a href="#Example_Class.Comparison_Functions" >Comparison Functions</a></div></div></div></td><td><div class=SGroup><div class=SDescription><div class=SIndent1></div></div></div></td></tr><tr class=SMarked><td><div class=SFunction><div class=SEntry><div class=SIndent2><a href="#Example_Class.IsEqual" id=link5 onMouseOver="ShowTip(event, 'ttIsEqual', 'link5')" onMouseOut="HideTip('ttIsEqual')">IsEqual</a></div></div></div></td><td><div class=SFunction><div class=SDescription><div class=SIndent2>Returns whether two integers are equal.</div></div></div></td></tr></table></div></div></div></div><div class=Topic><a name="JavadocCompatibility"></a><div class=TopicTitle>Javadoc Compatibility</div><p>If you have <a href="../languages.html">full language support</a> Natural Docs will also extract documentation from actual Javadoc comments, not just Natural Docs comments written with the Javadoc comment symbols.&nbsp; This provides you with a good method of migrating to Natural Docs as you don&rsquo;t have to convert all of your existing documentation.</p><pre class=Example>/**
+ * Multiplies two integers.
+ *
+ * @param x The first integer.
+ * @param y The second integer.
+ * @return The two integers multiplied together.
+ * @see Divide
+ */
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><h3 class=CTitle><a name="Example_Class.Multiply"></a>Multiply</h3><div class=CBody><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>int Multiply (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table><p class=CParagraph>Multiplies two integers.</p><h4 class=CHeading>Parameters</h4><table border=0 cellspacing=0 cellpadding=0 class=CDescriptionList><tr><td class=CDLEntry>x</td><td class=CDLDescription>The first integer.</td></tr><tr><td class=CDLEntry>y</td><td class=CDLDescription>The second integer.</td></tr></table><h4 class=CHeading>Returns</h4><p class=CParagraph>The two integers multiplied together.</p><h4 class=CHeading>See Also</h4><p class=CParagraph><a href="#Example_Class.Divide" class=LFunction id=link116 onMouseOver="ShowTip(event, 'ttDivide', 'link116')" onMouseOut="HideTip('ttDivide')">Divide</a></p></div></div></div></div><p>While most Javadoc tags and simple HTML formatting are supported, Natural Docs is not a full Javadoc parser and may not support some advanced tags and HTML.&nbsp; See <a href="../documentation/html/files/Modules/NaturalDocs/Parser/JavaDoc-pm.html">this page</a> for a list of what&rsquo;s supported and what isn&rsquo;t.</p><p>A source file can contain both Natural Docs and Javadoc comments.&nbsp; However, you cannot mix the two within a single comment.&nbsp; For example, you can&rsquo;t use asterisks for bold in a <code>@param</code> line.&nbsp; If a comment is written with the Javadoc comment symbols (repeat the last symbol of the first line once) doesn&rsquo;t have a topic line (like &ldquo;<code>Function: Multiply</code>&rdquo;) and uses Javadoc tags (like <code>@param</code>) the comment is treated as Javadoc.&nbsp; If any of those conditions aren&rsquo;t true it&rsquo;s treated as a Natural Docs comment.</p></div></td></tr><tr><td></td><td class=SideMenuBottom><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td class=SideMenuBottomLeft><img src="../images/menu/bottomleft.png" width=18 height=19></td><td class=SideMenuBottomRight><img src="../images/menu/bottomright.png" width=18 height=19></td></tr></table></td><td class=BodyBottom>Copyright &copy; 2003-2008 Greg Valure</td></tr></table><script language=JavaScript><!--
+ClosingBrowserTags();// --></script></body></html>

data/template/assets/naturaldocs/NaturalDocs/Help/documenting/walkthrough.html ADDED

@@ -0,0 +1,180 @@
+<html><head><title>Documenting Your Code - Walkthrough - Natural Docs</title><link rel=stylesheet type="text/css" href="../styles.css"><link rel=stylesheet type="text/css" href="../examples.css"><script language=JavaScript src="../javascript/PNGHandling.js"></script><script language=JavaScript src="../javascript/BrowserStyles.js"></script><script language=JavaScript src="../example/NaturalDocs.js"></script></head><body marginwidth=0 marginheight=0 leftmargin=0 topmargin=0><script language=JavaScript><!--
+OpeningBrowserTags();// --></script>
+<!-- saved from url=(0026)http://www.naturaldocs.org -->
+<table width=100% border=0 cellspacing=0 cellpadding=0><tr><td colspan=3 class=Header><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td><img src="../images/header/leftside.png" width=30 height=75><a href="../index.html"><img src="../images/header/logo.png" width=524 height=75 alt="Natural Docs"></a></td><td align=right><img src="../images/header/rightside.png" width=30 height=75></td></tr></table></td></tr><tr><td><img src="../images/header/overleftmargin.png" width=10 height=6></td><td class=SideMenuTop><img src="../images/header/overmenu.png" width=14 height=6></td><td class=BodyTop><img src="../images/header/overbody.png" width=24 height=6></td></tr><tr><td></td><td class=SideMenu nowrap><div class=SideMenuSection><div class=SideMenuTitle><img src="../images/menu/about.png" width=52 height=13 alt="About"></div><div class=SideMenuBody><a href="../languages.html" class=SideMenuEntry>Language Support</a><a href="../output.html" class=SideMenuEntry>Output Formats</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="../images/menu/using.png" width=45 height=13 alt="Using"></div><div class=SideMenuBody><a href="../documenting.html" class=SideMenuEntry id=SelectedSideMenuEntry>Documenting<br>Your Code</a><a href="../keywords.html" class=SideMenuEntry>Keywords</a><a href="../running.html" class=SideMenuEntry>Running</a><a href="../troubleshooting.html" class=SideMenuEntry>Troubleshooting</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="../images/menu/customizing.png" width=96 height=13 alt="Customizing"></div><div class=SideMenuBody><a href="../menu.html" class=SideMenuEntry>Organizing the Menu</a><a href="../styles.html" class=SideMenuEntry>CSS Styles</a><a href="../customizingtopics.html" class=SideMenuEntry>Topics and Keywords</a><a href="../customizinglanguages.html" class=SideMenuEntry>Languages, Indexes,<br>and Prototypes</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="../images/menu/community.png" width=86 height=13 alt="Community"></div><div class=SideMenuBody><a href="http://www.naturaldocs.org/" class=SideMenuEntry>Web Site</a><a href="http://www.naturaldocs.org/mailinglist.html" class=SideMenuEntry>Mailing Lists</a><a href="http://www.naturaldocs.org/messageboards.html" class=SideMenuEntry>Message Boards</a><a href="http://www.naturaldocs.org/bugs.html" class=SideMenuEntry>Bugs and<br>Feature Requests</a></div></div></td><td class=Body width=100%><div class=PageTitle>Documenting Your Code</div><div class=TOC><a href="#OurFirstFunction">Our First Function</a> &middot; <a href="#ClassesAndScope">Classes and Scope</a> &middot; <a href="#MoreFormatting">More Formatting</a><br><a href="#MoreOnLinking">More on Linking</a> &middot; <a href="#ExtraDocumentation">Extra Documentation</a> &middot; <a href="#AbbreviatedSyntax">Abbreviated Syntax</a></div><div class=Topic><a name="OurFirstFunction"></a><div class=TopicTitle>Our First Function</div><p>So you downloaded Natural Docs, you <a href="../running.html">figured out the command line</a>, and now it&rsquo;s time to start documenting your code.&nbsp; Natural Docs tries to make this very straightforward and painless, so let&rsquo;s just dive right in:</p><pre class=Example>/*
+   Function: Multiply
+   Multiplies two integers and returns the result.
+*/
+int Multiply (int x, int y)
+   {  return x * y;  };
+</pre><p>That&rsquo;s all you need.&nbsp; Run Natural Docs and here&rsquo;s what appears in your output:</p><div class=NDContent><div class=CFunction><div class=CTopic><h3 class=CTitle><a name="Multiply"></a>Multiply</h3><div class=CBody><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>int Multiply (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table><p class=CParagraph>Multiplies two integers and returns the result.</p></div></div></div></div><p>Okay, so that&rsquo;s all you need, but probably not all you want.&nbsp; After all, you&rsquo;ve got some real functions to document, not little one-liners.&nbsp; Here&rsquo;s something more elaborate:</p><pre class=Example>/*
+   Function: Multiply
+   Multiplies two integers.
+   Parameters:
+      x - The first integer.
+      y - The second integer.
+   Returns:
+      The two integers multiplied together.
+   See Also:
+      &lt;Divide&gt;
+*/
+int Multiply (int x, int y)
+   {  return x * y;  };
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><h3 class=CTitle><a name="Example_Class.Multiply"></a>Multiply</h3><div class=CBody><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>int Multiply (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table><p class=CParagraph>Multiplies two integers.</p><h4 class=CHeading>Parameters</h4><table border=0 cellspacing=0 cellpadding=0 class=CDescriptionList><tr><td class=CDLEntry>x</td><td class=CDLDescription>The first integer.</td></tr><tr><td class=CDLEntry>y</td><td class=CDLDescription>The second integer.</td></tr></table><h4 class=CHeading>Returns</h4><p class=CParagraph>The two integers multiplied together.</p><h4 class=CHeading>See Also</h4><p class=CParagraph><a href="#Example_Class.Divide" class=LFunction id=link116 onMouseOver="ShowTip(event, 'ttDivide', 'link116')" onMouseOut="HideTip('ttDivide')">Divide</a></p></div></div></div></div><div class=CToolTip id="ttAdd"><div class=CFunction><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>int Add (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Adds two integers.</div></div><div class=CToolTip id="ttSubtract"><div class=CFunction><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>int Subtract (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Subtracts two integers.</div></div><div class=CToolTip id="ttMultiply"><div class=CFunction><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>int Multiply (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Multiplies two integers.</div></div><div class=CToolTip id="ttDivide"><div class=CFunction><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>int Divide (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Divides two integers.</div></div><div class=CToolTip id="ttIsEqual"><div class=CFunction><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters>bool IsEqual (</td><td class=PType>int&nbsp;</td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int&nbsp;</td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Returns whether two integers are equal.</div></div><p>Still not too scary, huh?&nbsp; Notice the comments are just as readable as the output.&nbsp; No tags littered about, and the structure is very natural.&nbsp; You probably get it just by looking at it, but let&rsquo;s go through the details anyway.</p><pre class=Example>Function: Multiply
+</pre><p>Every one of these comments you write (called <i>topics</i>) are going to start with a <i>topic line</i> in the format <code>&ldquo;keyword: title&rdquo;</code>.&nbsp; There are <a href="../keywords.html">a lot of keywords</a>, but they&rsquo;re exactly what you&rsquo;d expect: Function, Class, Variable, etc.&nbsp; There are also a lot of synonyms so instead of Function you could use Func, Procedure, Proc, Method, Constructor, etc.&nbsp; It&rsquo;s designed so you can just use whatever it is you&rsquo;re describing without memorizing anything.&nbsp; You can glance over <a href="../keywords.html">the keyword list</a> but you shouldn&rsquo;t have to consult it very often.</p></p><p>The other part of the topic line is the title.&nbsp; It should match whatever it is you&rsquo;re documenting, in this case the function name Multiply.&nbsp; Natural Docs is case sensitive even if your programming language isn&rsquo;t, so make sure you match it closely or you might not get the prototype in your output, which is the little gray box.&nbsp; You don&rsquo;t need to include the parameters in the title.&nbsp; In fact, it&rsquo;s better if you don&rsquo;t.</p></p><pre class=Example>Parameters:
+Returns:
+See Also:
+</pre><p>You can also define <a href="reference.html#Headings">headings</a> by skipping a line and ending the text with a colon.&nbsp; If you&rsquo;re used to other documentation systems you may think there&rsquo;s only a handful of headings to choose from, but any text formatted this way will become one.&nbsp; If you want a heading called Dependencies you can go right ahead and add it.</p><pre class=Example>x - The first integer.
+y - The second integer.
+</pre><p>This is what&rsquo;s called a <a href="reference.html#DefinitionLists">definition list.</a>&nbsp; You can use more than one line to finish the definition, as it won&rsquo;t stop until you skip a line.</p><pre class=Example>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.
+</pre><p>Indentation doesn&rsquo;t matter either, so even if the second description line wasn&rsquo;t indented to match the first, it would still be considered part of it.</p><pre class=Example>&lt;Divide&gt;
+</pre><p>This is how we link in Natural Docs, with angle brackets.&nbsp; There will be a lot more to say about this later, but for now I&rsquo;ll just show you something cool.&nbsp; Hover over it in the output below:</p><div class=NDContent><div class=CTopic><div class=CBody><p class=CParagraph><a href="#Example_Class.Divide" class=LFunction id=link116 onMouseOver="ShowTip(event, 'ttDivide', 'link216')" onMouseOut="HideTip('ttDivide')">Divide</a></p></div></div></div><p>You get that <i>everywhere</i> in your generated documentation.</p></div><div class=Topic><a name="ClassesAndScope"></a><div class=TopicTitle>Classes and Scope</div><p>So that&rsquo;s good for our one function of questionable usefulness, but what if we have a whole class of questionable usefulness?&nbsp; We can document the class and it&rsquo;s members the same way we documented the individual function, with a Natural Docs comment right above each element.&nbsp; We&rsquo;ll go back to short descriptions to keep the example manageable.</p><pre class=Example>/*
+   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;
+   };
+</pre><p>Everything&rsquo;s the same, we just substituted Class and Variable for the Function keyword when it was appropriate.&nbsp; We also used Constructor, but we could have just as easily used Function there too.&nbsp; They&rsquo;re both keywords for the same thing so it doesn&rsquo;t matter.</p><a name="Scope"></a><div class="SubTopic">Scope</div><p>Like the source code itself, Natural Docs topics have <a href="reference.html#Scope">scope.</a>&nbsp; Value and Increment are seen as part of class Counter, just like they are in the code.&nbsp; Why is this important?&nbsp; Linking.&nbsp; Linking from one topic to another has similar rules to how one function can call another.&nbsp; Since Value is in the same class as Increment, it&rsquo;s topic can link to it with just <code>&lt;Increment&gt;</code>.&nbsp; However, linking to Increment from a different class would require <code>&lt;Counter.Increment&gt;</code> instead.&nbsp; You can actually use any of the three most common class/member notations: <code>&lt;Counter.Increment&gt;</code>, <code>&lt;Counter::Increment&gt;</code>, and <code>&lt;Counter-&gt;Increment&gt;</code>.</p><p>If your programming language has <a href="../languages.html">full language support</a>, the scope is determined by the code and applied automatically.&nbsp; However, if you only have <a href="../languages.html">basic language support</a> it follows these rules:</p><ul><li>Any topic that appears under a Class topic (or anything that says <a href="../keywords.html">Starts Scope</a>) is part of that class.</li><li>Any topic that appears under a Section topic (or anything that says <a href="../keywords.html">Ends Scope</a>) is global again.</li><li>Any File topic (or anything that says <a href="../keywords.html">Always Global</a>) is global no matter what and doesn&rsquo;t affect any other topics.</li><p></ul></p><p>Chances are you would have written the same thing even if you didn&rsquo;t know this and it would have just worked.&nbsp; You usually won&rsquo;t need to think about them at all.&nbsp; However, it&rsquo;s still good to be aware of them in case something doesn&rsquo;t behave the way you expected it to.</p><p>You actually know enough to go start documenting now.&nbsp; I know Mr. ScrollBar says there&rsquo;s more on this page you can learn, but if you want to skip out early, you can.&nbsp; Really.&nbsp; I don&rsquo;t mind.</p></div><div class=Topic><a name="MoreFormatting"></a><div class=TopicTitle>More Formatting</div><p>Okay then.&nbsp; On we go.</p><a name="ParagraphsBoldAndUnderline"></a><div class="SubTopic">Paragraphs, Bold, and Underline</div><p>The syntax for these three is exactly what you would expect it to be.</p><pre class=Example>*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.
+</pre><div class=NDContent><div class=CBody><div class=CFunction><div class=CTopic><p><b>Bold text</b></p><p><u>Underlined text</u></p><p>Paragraphs are broken by skipping lines.&nbsp; So the two lines above each have their own paragraph, but these three lines are all part of the same one.</p></div></div></div></div><p>When underlining multiple words, you can use an underscore for each space or only put them at the edges like we did above.&nbsp; Both ways will work.</p><a name="BulletLists"></a><div class="SubTopic">Bullet Lists</div><p>You can add <a href="reference.html#BulletLists">bullet lists</a> by starting a line with a dash, an asterisk, an o, or a plus.&nbsp; Like definition lists, bullets can span multiple lines and indentation doesn&rsquo;t matter.&nbsp; To end a bullet you have to skip a line before doing something else.</p><pre class=Example>- Bullet one.
+- Bullet two.
+  Bullet two continued.
+- Bullet three.
+Some text after the bullet list.
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><ul class=CBulletList><li>Bullet one.</li><li>Bullet two.&nbsp; Bullet two continued.</li><li>Bullet three.</li></ul><p class=CParagraph>Some text after the bullet list.</p></div></div></div></div><a name="CodeAndTextDiagrams"></a><div class="SubTopic">Code and Text Diagrams</div><p>You can add <a href="reference.html#CodeAndTextDiagrams">example code or text diagrams</a> by starting each line with <code>&gt;</code>, <code>|</code>, or <code>:</code>.</p><pre class=Example>&gt; a = b + c;
+&gt; b++;
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><pre class=CCode>a = b + c;<br>b++;</pre></div></div></div></div><p>If you have a long stretch, you can use <code>(start code)</code> and <code>(end)</code> instead.</p><pre class=Example>(start code)
+if (x == 0) {
+   DoSomething();
+}
+return x;
+(end)
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><pre class=CCode>if (x == 0) {<br>   DoSomething();<br>}<br><br>return x;</pre></div></div></div></div><p>You can also use <code>example</code>, <code>diagram</code>, or <code>table</code> instead of <code>code</code>.&nbsp; Just use whatever&rsquo;s appropriate.</p><p>As I mentioned before, we don&rsquo;t want you to worry about memorizing minor details, so in that spirit it will also accept <code>begin</code> for <code>start</code> and <code>finish</code> or <code>done</code> for <code>end</code>.&nbsp; You can also write <code>(end code)</code> instead of just <code>(end)</code>.</p><a name="Images"></a><div class="SubTopic">Images</div><p>You can include images in your documentation by writing &ldquo;<code>(see filename)</code>&rdquo;.&nbsp; 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.</p><pre class=Example>This is the first paragraph.
+(see logo.gif)
+This is the second paragraph (see logo.gif)  This
+is more of the second paragraph.
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><p class=CParagraph>This is the first paragraph.</p><img src="../images/logo.gif" width="268" height="61"><p class=CParagraph>This is the second paragraph <a href="#Image1" class=CImageLink>(see logo)</a>&nbsp; This is more of the second paragraph.</p><div class=CImage><a name="Image1"></a><div class=CImageCaption>logo</div><img src="../images/logo.gif" width="268" height="61"></div></div></div></div></div><p>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 <code>(see Images/Logo.gif)</code>.&nbsp; However, you can also specify image directories in <a href="../running.html#CommandLine">the command line with <code>-img</code></a>, so if all your source files are in C:\Project\Source and all your images are in C:\Project\Images, you can put &ldquo;<code>-img C:\Project\Images</code>&rdquo; on the command line and just use <code>(see logo.gif)</code> again.</p></div><div class=Topic><a name="MoreOnLinking"></a><div class=TopicTitle>More on Linking</div><p>Yes, there&rsquo;s still more to linking.&nbsp; You can link to URLs and e-mail addresses, but in this case the angle brackets are optional.</p><pre class=Example>Visit &lt;http://www.website.com&gt; or send messages to
+email@address.com.
+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><p class=CParagraph>Visit <a href="#" onClick="return false;" class=LURL>http://www.website.com</a> or send messages to <a href="#" onclick="location.href='mai' + 'lto:' + 'em' + 'ail' + '@' + 'addre' + 'ss.com'; return false;" class="LEMail">em<span style="display: none;">.nosp@m.</span>ail<span>@</span>addre<span style="display: none;">.nosp@m.</span>ss.com</a>.</p></div></div></div></div><p>E-mail addresses are protected from spam crawlers.&nbsp; They look and act like regular links (try it above) but you can see the actual HTML that&rsquo;s generated for them <a href="reference.html#URLsAndEMail">here</a>.</p><p>As for regular links, to help them fit into sentences easily you can actually include plurals and possessives inside the angle brackets.&nbsp; In other words, you don&rsquo;t have to use awkward syntax like <code>&lt;Object&gt;s</code>, although that&rsquo;s supported as well.&nbsp; You can simply write <code>&lt;Objects&gt;</code> and it will link to the symbol <code>Object</code> just fine.&nbsp; It can handle any plural and/or possessive form you can throw at it.&nbsp; I&rsquo;m not kidding: <code>Foxes</code>, <code>Fox&rsquo;s</code>, <code>Foxes&rsquo;</code>, <code>Children</code>, <code>Mice</code>, <code>Alumni</code>, <code>Indices</code>, <code>Amoebae</code>, <code>Teeth</code>, just try to trip it up.</p></div><div class=Topic><a name="ExtraDocumentation"></a><div class=TopicTitle>Extra Documentation</div><p>Sometimes you want to include documentation that doesn&rsquo;t correspond directly to a code element.&nbsp; Maybe you want to include license information or architecture notes.&nbsp; There are two ways to do this.</p><a name="FreestandingTopics"></a><div class="SubTopic">Freestanding Topics</div><p>Just because most of the things you write will directly correspond to an element of your source code doesn&rsquo;t mean they have to.&nbsp; You can pick any of <a href="../keywords.html">the available keywords</a> and create a freestanding comment with it.&nbsp; For example:</p><pre class=Example>/*
+   Class: Counter
+   A class that manages an incrementing counter.
+*/
+class Counter
+   {
+   public:
+      /*
+         About: License
+         This file is licensed under the GPL.
+      */
+      /*
+         Constructor: Counter
+         Initializes the object.
+      */
+      Counter()
+         {  value = 0;  };
+   ...
+</pre><p>The extra license topic will be added to the output just like the functions.</p><div class=NDContent><div class=CFunction><div class=CTopic><h3 class=CTitle>License</h3><div class=CBody><p class=CParagraph>This file is licensed under the GPL.</p></div></div></div></div><p>Remember that because of <a href="#Scope">scope</a>, the License topic will actually be considered part of Counter the way it&rsquo;s listed above.&nbsp; You&rsquo;d link to it from outside Counter with <code>&lt;Counter.License&gt;</code>.&nbsp; That idea may take some getting used to, but if an extra topic only applies to one class that&rsquo;s actually the most appropriate way to do it.&nbsp; In this case it&rsquo;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.</p><a name="TextFiles"></a><div class="SubTopic">Text Files</div><p>You can also add additional documentation with text files.&nbsp; If you put a file with a .txt extension in your source tree and start it with a topic line, it&rsquo;s contents will be treated the same as if it were in a comment in your source code.&nbsp; 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.</p><pre class=Example>Title: License
+This file is licensed under the GPL.
+I can link to &lt;Counter&gt; and &lt;Counter.Increment&gt;, and
+the documentation in that class can even link back
+with &lt;License&gt;.
+About: Second Topic
+I can create a *second* topic in here too, complete
+with formatting.
+</pre><p>The thing some people forget though is that you <b>must</b> start it with a topic line, like &ldquo;<code>Title: License</code>&rdquo; above.&nbsp; This is how Natural Docs tells it apart from regular text files.</p></div><div class=Topic><a name="AbbreviatedSyntax"></a><div class=TopicTitle>Abbreviated Syntax</div><p>Here&rsquo;s another useful thing you may want to know about.&nbsp; Suppose you have a lot of little things to document, like constants.&nbsp; Writing a separate topic for each one can be very tedious, no matter how much you compress it:</p><pre class=Example>// 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
+</pre><p>One thing you may have noticed in the <a href="../keywords.html">keyword list</a> is that they almost all have plural forms.&nbsp; These are used to create what are called <a href="reference.html#ListTopics">list topics.</a>&nbsp; You define a topic using a plural keyword, and then anything appearing in a <a href="reference.html#DefinitionLists">definition list</a> within it creates a linkable symbol as if they each had their own topic.&nbsp; For example:</p><pre class=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
+</pre><p>I would now be able to write <code>&lt;COUNTER_ODD&gt;</code> and have it work the same as it would with the first example.</p><p>Using the enum or enumeration keyword is special because it automatically behaves in a similar manner.&nbsp; This allows both the enum and its values to be documented in the same place.</p><pre class=Example>/*
+   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 };
+</pre><p>That&rsquo;s it, you&rsquo;re done with this walkthrough.&nbsp; You should know enough now to make very good use of Natural Docs.&nbsp; If you still want to know more, you can look in <a href="reference.html">the reference</a> for some of the smaller details we may have skipped over.&nbsp; Also, look at the Customizing pages on this web site for even more you can do.</p></div></td></tr><tr><td></td><td class=SideMenuBottom><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td class=SideMenuBottomLeft><img src="../images/menu/bottomleft.png" width=18 height=19></td><td class=SideMenuBottomRight><img src="../images/menu/bottomright.png" width=18 height=19></td></tr></table></td><td class=BodyBottom>Copyright &copy; 2003-2008 Greg Valure</td></tr></table><script language=JavaScript><!--
+ClosingBrowserTags();// --></script></body></html>