autodoc.git/ traditional_manual/ chapter_21.html

Branch: Tag:

2019-07-04

2019-07-04 12:45:39 by Henrik Grubbström (Grubba) <grubba@grubba.org>

Documentation [Traditional]: Added some structure to the I/O chapter.

1:   <!doctype html><html><head><title>Pike Reference Manual</title>   <meta charset='utf-8'></head>   <body><dl><dt><h1 class='header'>21. Pike AutoDoc markup</h1></dt><dd></dd> - <dt><a name='1'></a> + <dt><a name='21.1'></a>   <h2 class='header'>21.1. Syntax</h2></dt> - <dd></dd><dt><h3 class='header'>21.1.1. Line orientation</h3></dt><dd><p>The markup is line oriented. If you need to write a line which is very + <dd></dd> + <dt><a name='21.1.1'></a> + <h3 class='header'>21.1.1. Line orientation</h3></dt> + <dd><p>The markup is line oriented. If you need to write a line which is very   long, it can be broken into several lines. A trailing <tt>@</tt> on the line   indicates that it continues on the next line. The <tt>@</tt> and the newline   character will be discarded, and the lines merged. Thus:</p><p></p><pre>
28:    &lt;p&gt; - I love you, said Danny.&lt;/p&gt;    &lt;p&gt; - You have no right to come here after what you did to    my little dog, screamed Penny in despair.&lt;/p&gt; - </pre></p></dd><dt><h3 class='header'>21.1.2. Keywords</h3></dt><dd><p>Keywords always begin with an at-sign: <tt>@</tt>. A <tt>@</tt> is quoted by writing two + </pre></p></dd> + <dt><a name='21.1.2'></a> + <h3 class='header'>21.1.2. Keywords</h3></dt> + <dd><p>Keywords always begin with an at-sign: <tt>@</tt>. A <tt>@</tt> is quoted by writing two   of them: <tt>@@</tt>. There are four types of keywords (the keywords in []'s   are examples of keywords of the different types):</p><ol>   <li><p> Meta keywords <tt>[@decl, @class, @endclass, @module and @endmodule]</tt>
76:    He is so &lt;i&gt;italic&lt;/i&gt; and &lt;b&gt;bold&lt;/b&gt;!!!    </pre></p></li>   </ol><p>NOTA BENE: Delimiter keywords (2) and block keywords (3) must stand - alone (with their parameters, if any) on one line.</p></dd><dt><h3 class='header'>21.1.3. Delimiter keyword grouping</h3></dt><dd><p>Delimiter keywords that indicate a new section inside the block can be + alone (with their parameters, if any) on one line.</p></dd> + <dt><a name='21.1.3'></a> + <h3 class='header'>21.1.3. Delimiter keyword grouping</h3></dt> + <dd><p>Delimiter keywords that indicate a new section inside the block can be   grouped together in the interest of not writing the same docstring for   multiple parameters etc. Delimiters are grouped if they appear on   consecutive lines. For example, when documenting a method:</p><p></p><pre>
94:    //! @note    //! Don't use this function. At all. Ever.   </pre><p></p> - </dd><dt><h3 class='header'>21.1.4. Keyword parameters</h3></dt><dd><p>After the leading <tt>@keyword</tt> (that may be preceded only by whitespace) + </dd> + <dt><a name='21.1.4'></a> + <h3 class='header'>21.1.4. Keyword parameters</h3></dt> + <dd><p>After the leading <tt>@keyword</tt> (that may be preceded only by whitespace)   on the line, the rest of the line is interpreted as a parameter list.   The syntax of this parameter list can be different depending on the   keyword:</p><ol>
147:       <p>The parameter will be a string with two characters, a backslash    followed by the letter n.</p></li> - </ol></dd><dt><h3 class='header'>21.1.5. Grammar</h3></dt><dd><p>Here comes a BNF-ish grammar for documentation blocks. Note that + </ol></dd> + <dt><a name='21.1.5'></a> + <h3 class='header'>21.1.5. Grammar</h3></dt> + <dd><p>Here comes a BNF-ish grammar for documentation blocks. Note that   before the parsing of the block, all lines ending with a <tt>@</tt> will be   merged with the next line (see (a) above)</p><p><pre>   docblock:
211:   white_space:    ' ' | '\t'   </pre></p></dd> - <dt><a name='2'></a> + <dt><a name='21.2'></a>   <h2 class='header'>21.2. Pike autodoc inlining</h2></dt>   <dd><p>The autodoc extractor works either in C mode or in Pike mode. The   reason why the two modes are not the same is that they perform two
225:   on its own, but for C files, where the directory structure gives   insufficient cues about what is what, there must be make targets set   up manually. All generated XML files can then be merged together into - the final Pike namespace.</p></dd><dt><h3 class='header'>21.2.1. C files</h3></dt><dd><p>In C files, the doc comments look like:</p><p></p><pre> + the final Pike namespace.</p></dd> + <dt><a name='21.2.1'></a> + <h3 class='header'>21.2.1. C files</h3></dt> + <dd><p>In C files, the doc comments look like:</p><p></p><pre>    /*! yadda yadda    *! yadda yadda yadda    */
266:   directives in assembler source files. That is, you can have <tt>@module   foo</tt> in several C files, if the module source is spread over multiple   files. However, if you write doc for the module itself in several - places, an error will be triggered.</p></dd><dt><h3 class='header'>21.2.2. Pike files</h3></dt><dd><p>Doc comments look like:</p><p></p><pre> + places, an error will be triggered.</p></dd> + <dt><a name='21.2.2'></a> + <h3 class='header'>21.2.2. Pike files</h3></dt> + <dd><p>Doc comments look like:</p><p></p><pre>    //! yadda yadda yadda    //! yadda yadda   </pre><p></p>
440:    //! @endignore   </pre><p></p>   </dd> - <dt><a name='3'></a> + <dt><a name='21.3'></a>   <h2 class='header'>21.3. Pike autodoc tags</h2></dt>   <dd><p>We have defined some different categories of markup, each with its own   semantics. Seen from the parser, there are two main construct levels:</p><ul>
461:      <li><p> short text markup constructs that basically map to XML containers    (<tt>@i{...@}, @ref{...@}</tt>)</p></li> - </ul></dd><dt><h3 class='header'>21.3.1. Meta level tags</h3></dt><dd><p>These tags all serve the purpose of denoting what pike entities your + </ul></dd> + <dt><a name='21.3.1'></a> + <h3 class='header'>21.3.1. Meta level tags</h3></dt> + <dd><p>These tags all serve the purpose of denoting what pike entities your   comments should be tied to. This is particularly needed in (and in   part only applies to) C files, where the autodoc extractor does not   try to interpret and parse class and method definitions.</p><p><pre>