mirror of
https://github.com/ddnet/ddnet.git
synced 2024-11-15 04:28:20 +00:00
160 lines
34 KiB
HTML
160 lines
34 KiB
HTML
|
|
||
|
|
|
||
|
|
<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"><!--
|
||
|
|
|
||
|
|
|
||
|
|
.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><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="messageboards.html" class=SideMenuEntry>Message Boards</a><a href="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> · <a href="#TextFiles">Text Files</a> · <a href="#Topics">Keywords, Topics, and Scope</a><br><a href="#FormattingAndLayout">Formatting and Layout</a> · <a href="#Linking">Linking</a> · <a href="#PageTitles">Page Titles</a> · <a href="#Summaries">Summaries</a></div><div class=Topic><p>You document your code by putting Natural Docs content in the comments or in text files. Before we go through all the specifics, here’s an example right off the bat so you have an idea of what it looks like. Here’s your code:</p><pre class=Example>/*
|
||
|
|
Function: Multiply
|
||
|
|
Multiplies two integers and returns the result.
|
||
|
|
*/
|
||
|
|
int Multiply (int x, int y)
|
||
|
|
{ return x * y; };</pre><p>And here’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 </td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int </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>Here’s a more elaborate example. This is overkill for this particular function, but you get the idea.</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:
|
||
|
|
|
||
|
|
<Divide>
|
||
|
|
*/
|
||
|
|
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 </td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int </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, 'tt4', 'link116')" onMouseOut="HideTip('tt4')">Divide</a></p></div></div></div></div><div class=CToolTip id="tt1"><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 </td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int </td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Adds two integers.</div></div><div class=CToolTip id="tt2"><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 </td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int </td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Subtracts two integers.</div></div><div class=CToolTip id="tt3"><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 </td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int </td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Multiplies two integers.</div></div><div class=CToolTip id="tt4"><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 </td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int </td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Divides two integers.</div></div><div class=CToolTip id="tt5"><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 </td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int </td><td class=PParameter>y</td><td class=PAfterParameters>)</td></tr></table></td></tr></table>Returns whether two integers are equal.</div></div><p>Not too scary, huh? Notice the comments are just as readable as the output. No tags littered about, and the structure is very natural. This was one of the goals of Natural Docs. Anyway, on to the details.</p></div><div class=Topic><a name=Comments></a><div class=TopicTitle>Comments</div><p>There is no special comment style for Natural Docs. You just embed Natural Docs topics into regular comments, and it’s pretty tolerant as far as style goes. You can use block comments or line comments strung together. The only requirement is that the comments are alone on a line. Comments appe
|
||
|
|
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. If a line is completely blank, it’s considered the end of the comment and thus the end of the Natural Docs topic.</p><div class=SubTopic>Boxes and Horizontal Lines</div><p>Natural Docs can also handle comment boxes and horizontal lines. It doesn’t matter what symbols they use or how thick the lines are. The boxes don’t need to be closed on the right side, and they can have different symbols for the edges and corners.</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><div class=SubTopic>POD</div><p>Perl users can use POD to do block comments.</p><pre class=Example>=begin nd
|
||
|
|
|
||
|
|
Function: Multiply
|
||
|
|
Multiplies two integers and returns the result.
|
||
|
|
|
||
|
|
=cut
|
||
|
|
|
||
|
|
|
||
|
|
=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>. None of them are case sensitive. 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><b>Important:</b> The second form of just <code>=nd</code> is offered as a convenience but is not valid POD. Perl will skip over it and execute fine, but POD parsers will give errors and possibly include the unformatted text in the output. Use the longer, valid form unless you know for certain that no one will ever try to run POD on your code.</p></div><div class=Topic><a name=TextFiles></a><div class=TopicTitle>Text Files</div><p>Alternately, documentation can be included in text files. Any file with a .txt extension appearing in the source tree will be scanned for Natural Docs topics. It will be treated the same as a source file, meaning it will appear in the menu, its topics will be in the indexes, and its topics can be linked to from anywhere in the documentation. The only difference is you don’t need comment symbols.</p><p>Note that you still need to include topic headers, though. Anything before the first header will be ignored, and if the file doesn’t have any header lines at all, it will be ignored completely.</p><p>This method is convenient for documenting file formats, configuration settings, the general program architecture, or anything else that isn’t directly tied to a source file.</p></div><div class=Topic><a name=Topics></a><div class=TopicTitle>Keywords, Topics, and Scope</div><p>As you may have guessed, a topic in Natural Docs starts with a <code>“keyword: name”</code> line. You can have multiple topics per comment as long as you separate them with a blank line. The keywords aren’t case sensitive.</p><p>The list of keywords is pretty predictable: <code>Function</code>, <code>Class</code>, <code>Variable</code>, etc. Just use what they are. There are many synonyms as well, so you can use keywords like <code>Func</code>, <code>Procedure</code>, <code>Proc</code>, <code>Method</code> and <code>Constructor</code>. Look at the <a href="keywords.html">full list of keywords</a> to see everything that’s available.</p><p>The <a href="keywords.html">list of keywords</a> is separated into topic types. Each type gets its own index, and which specific keyword you use doesn’t matter. Some also have scoping rules or other behavior as noted.</p><div class=SubTopic>Scope</div><p>Like the code it’s documenting, Natural Docs topics have scope. This mostly has to do with <a href="#Linking">linking</a>: if you’re in a class you can link to its members by their name alone, but if you’re not, you have to use a notation like <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. If you’re using text files or only have basic language support, scoping follows these basic rules:</p><ul><li>Everything after a class topic (or <a href="keywords.html">anything that says “Starts Scope”</a>) is part of that class.</li><li>Everything after a section topic (or <a href="keywords.html">anything that says “Ends Scope”</a>) is global again.</li><li>File topics (or <a href="keywords.html">anything that says “Always Global”</a>) are global but do not change the scope for anything else.</li></ul><div class=SubTopic>List Topics</div><p>If you looked at the list, you saw that most of the keywords have plural forms. That’s for list topics, which let you document many small things without using the full syntax. Anything that appears in <a href="#DefinitionList">definition lists</a> within that topic will be treated as if it had its own topic. It will appear in the index
|
||
|
|
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><div class=SubTopic>Bold and Underline</div><p>You can apply bold to a stretch of text by surrounding it with asterisks. You can apply underlining by surrounding it with underscores instead. With underlining, it doesn’t matter if you use an underscore for every space between words or not; they’ll be converted to spaces if you do.</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><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. You can skip the blank after it but not before.</p> <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. Bullets can have blank lines between them if you want, and subsequent lines don’t have to be indented. You end a list by skipping a line and doing something else.</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. 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. 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=DefinitionList></a><div class=SubTopic>Definition Lists</div><p>You can add a definition list by using the format below, specifically “text space dash space text”. Like bullet lists, you can have blank lines between them if you want, subsequent lines don’t have to be indented, and you end the list by skipping a line and doing something else. The first line of the list must be after a blank line or something like a header; it can’t be</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. This is more of the second item.</td></tr><tr><td class=CDLEntry>Third</td><td class=CDLDescription>This is the third item. 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’re using the plural form of the keywords each entry is a symbol and can be linked to just as if it had its own topic.</p><a name=Code></a><div class=SubTopic>Code and Text Diagrams</div><p>Finally, you can add example code or text diagrams by starting each line with >, |, or :. If you have a vertical line or text box with the comment, you must separate these symbols from it with a space.</p><pre class=Example>: a = b + c;
|
||
|
|
|
||
|
|
> +-----+ +-----+
|
||
|
|
> | A | --> | B |
|
||
|
|
> +-----+ +-----+
|
||
|
|
> |
|
||
|
|
> +-----+
|
||
|
|
> | C |
|
||
|
|
> +-----+</pre><div class=NDContent><div class=CFunction><div class=CTopic><div class=CBody><pre class=CCode>a = b + c;</pre><pre class=CCode>+-----+ +-----+
|
||
|
|
| A | --> | B |
|
||
|
|
+-----+ +-----+
|
||
|
|
|
|
||
|
|
+-----+
|
||
|
|
| C |
|
||
|
|
+-----+</pre></div></div></div></div><p>For long stretches, this may be too tedious. You can start a code section by placing <code>(start code)</code> or just <code>(code)</code> alone on a line. You end it with either <code>(end code)</code> or just <code>(end)</code>. You can’t put any other content on these lines other than any line or text box symbols you may be using with the comment.</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) {
|
||
|
|
DoSomething();
|
||
|
|
}
|
||
|
|
|
||
|
|
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>. Just use whatever’s appropriate. 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’t have to remember the exact word.</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. Of course, the alternative would be to automatically guess where links should be, but systems that do that typically pepper your sentences with unintentional links to functions called “is” or “on”. However, the Natural Docs syntax is still as minimal as possible. Simply surround any topic you want to link to with angle brackets. Natural Docs will keep track off all the topics and where they are defined, so you don’t need to use HTML-like syntax or remember what file anything is in. Also, if the link can’t be resolved to anything, Natural Docs leaves the angle brackets in the output so if something wasn’t intended to be a link (such as <code>#include <somefile.h></code>) it won’t be mangled.</p><pre class=Example>Let's link to function <Multiply>.</pre><div class=NDContent><p class=CParagraph>Let’s link to function <a href="#Example_Class.Multiply" class=LFunction id=link632 onMouseOver="ShowTip(event, 'tt3', 'link632')" onMouseOut="HideTip('tt3')">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’t matter if you include empty parenthesis or not. Both <code><Function></code> and <code><Function()></code> will work. However, if you documented the function with parameters as part of the name, you will need to include those parameters whenever linking to it. It is recommended that you only include parameters in the topic name if you need to distinguish between two functions with the same name.</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. If the topic has a prototype, that will be included as well. You can try it above.</p><div class=SubTopic>Scope</div><p>If a topic is <a href="#Topics">considered part of a class</a>, they are linked to using any of the three most common class/member notations: <code>class.member</code>, <code>class::member</code>, and <code>class->member</code>. Natural Docs will not be confused by <code><class->member></code>. Like in the language itself, if the topic you’re writing is in that class’ scope you can link to it simply as <code><member></code>.</p><p>If you have multi-level classes and packages, links can be relative as well. So if you’re in <code>Project::UI::Window::Base</code> and you want to link to <code>Project::UI::Button::Base</code>, just using <code><Button::Base></code> will work. Links will try to resolve to globals before relative because not everyone wants to use relative links, and this way they can ignore it without anything getting messed up.</p><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. In other words, you don’t have to use awkward syntax like <code><Object>s</code>, although that’s supported as well. You can simply write <code><Objects></code> and it will link to the symbol <code>Object</code> just fine. It can handle any plural and/or possessive form you can throw at it. I’m not kidding: <code>Foxes</code>, <code>Fox’s</code>, <code>Foxes’</code>, <code>Children</code>,
|
||
|
|
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;">(delete this)</span>ail<span>@</span>addre<span style="display: none;">(delete this)</span>ss.com</a>.</p></div></div></div></div><p>E-mail addresses are protected in a way that should avoid spam crawlers. Although the link above looks and acts like a regular link (try it) the HTML code actually looks like this:</p><pre><a href="#"
|
||
|
|
onClick="location.href='mai' + 'lto:' + 'em' + 'ail' + '@'
|
||
|
|
+ 'addre' + 'ss.com'; return false;">
|
||
|
|
em<span style="display: none">.nosp@m.</span>ail
|
||
|
|
<span>@</span>
|
||
|
|
addre<span style="display: none">.nosp@m.</span>ss.com
|
||
|
|
</a></pre></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’s only one topic in the file, that topic’s title becomes the page title.</li><li>Otherwise, if the first topic in the file is a class, section, or file, that topic’s title becomes the page title.</li><li>Otherwise, the file name becomes the page title.</li></ul><p>This should be enough for most people. However, if you don’t like the page title Natural Docs has chosen for you, add a “<code>Title: [name]</code>” comment to the top of the file to override it. <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><div class=TopicTitle><a name=Summaries></a>Summaries</div><p>Summaries are automatically generated for every file, class, and section. You don’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. The first is that they use the first sentence in the topic as the description, so long as it’s plain text and not something like a bullet list. It will also appear in the tooltip whenever that topic is linked to.</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. Natural Docs will automatically group them by type if you do not, but sometimes you want to be more specific. You don’t need to provide a description, just adding a “<code>Group: [name]</code>” comment is sufficient. Note that once you manually add a group automatic grouping is completely turned off for that class.</p><p>Here’s an example summary. Note that as before, when you hover over a link, you’ll get the prototype and summary line as a tooltip.</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, 'tt1', 'link1')" onMouseOut="HideTip('tt1')">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, 'tt2', 'link2')" onMouseOut="HideTip('tt2')">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, 'tt3', 'link3')" onMouseOut="HideTip('tt3')">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, 'tt4', 'link4')" onMouseOut="HideTip('tt4')">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=SG
|
||
|
|
Function: Multiply
|
||
|
|
|
||
|
|
Multiplies two integers.
|
||
|
|
|
||
|
|
Parameters:
|
||
|
|
|
||
|
|
x - The first integer.
|
||
|
|
y - The second integer.
|
||
|
|
|
||
|
|
Returns:
|
||
|
|
|
||
|
|
The two integers multiplied together.
|
||
|
|
|
||
|
|
See Also:
|
||
|
|
|
||
|
|
<Divide>
|
||
|
|
*/
|
||
|
|
int Multiply (int x, int y)
|
||
|
|
{ return x * y; };</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 </td><td class=PParameter>x,</td><td></td></tr><tr><td></td><td class=PType>int </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=link36 onMouseOver="ShowTip(event, 'tt4', 'link36')" onMouseOut="HideTip('tt4')">Divide</a></p></div></div></div></div></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 © 2003-2005 Greg Valure</td></tr></table><script language=JavaScript><!--
|
||
|
|
ClosingBrowserTags();// --></script></body></html>
|