autodoc.git / traditional_manual / chapter_21.html

version» Context lines:

autodoc.git/traditional_manual/chapter_21.html: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>    //! @variable thisVariableNameIsSoLong@    //!YouJustCantBelieveIt   </pre><p></p>   <p>will appear to the parser as:</p><p></p><pre>    //! @variable thisVariableNameIsSoLongYouJustCantBelieveIt   </pre><p></p>   <p>This is sometimes necessary because keywords that take parameters
autodoc.git/traditional_manual/chapter_21.html:21:   paragraph break. Thus:</p><p></p><pre>    //! - I love you, said Danny.    //!    //! - You have no right to come here after what you did to    //! my little dog, screamed Penny in despair.   </pre><p></p>   <p>will generate the following XML:</p><p><pre>    &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>    Must stand alone on one line, preceded only by whitespace. These are    not really part of the markup. They must come before any text or    other keywords in the doc block. They provide information about what    is being documented etc. and do not result in any text in the    documentation. Meta keywords have keyword specific parameter    syntaxes.</p></li>   
autodoc.git/traditional_manual/chapter_21.html:69:    <example>    //! He is so @xml{&lt;i&gt;italic&lt;/i&gt; and @b{bold@}!@}!!    </example>       <p>will generate the following XML:</p>       <p><pre>    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>    //! @decl int dist(int x, int y)    //! Calculates the distance.    //! @param x    //! @param y    //! The coordinates of the vector.   </pre><p></p>   <p>Above, the two <tt>@param</tt>'s x and y are grouped together and share the   same docstring: "The coordinates of the vector.". It is an error to   try to group together different keywords:</p><p></p><pre>    //! Error, can't group @note and @param:    //! @param x    //! @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>   <li><p> Special keyword parameter list syntax    Here the parameters can be parsed according to Pike syntax or in    some other way. Examples of keywords that use these kinds of special    syntaxes are all the meta keywords, @member and @elem.</p></li>      <li><p> Default parameter list syntax    The meaning of parameters is determined by the order in which they
autodoc.git/traditional_manual/chapter_21.html:140:    <p>The parameters are not parsed so you can not have markup inside    them. Pike style quoting is not used either, which means that if    you write:</p>      <example>    //! @look "\n"   </example>       <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:    metaline*, blockbody      metaline:    start_of_line, white_space*, metakeyword, any_char_but_newline,    end_of_line      blockbody:
autodoc.git/traditional_manual/chapter_21.html:204:      keyword:    '@', alpha_char+      endblockkeyword:    '@end', alpha_char+      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   very different tasks. The C mode only has to find comments in the   file, and ignores the surrounding code totally, while the Pike mode on   the other hand is supposed to be smarter and distill a lot of   information from the Pike code that surrounds the comments.</p><p>Both work at the file level. That makes it easy to use for example   "make" to generate documentation for the source tree. Another benefit   is that the generation will not have to reparse all of the tree if   only one source file is changed.</p><p>For Pike module trees, the extractor can recurse through the file tree   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    */   </pre><p></p>   <p>Note that only lines that start with <tt>*!</tt> count, so above are only two   doc lines. Any whitespace before the leading <tt>*!</tt> is skipped, so that   the lines can be indented freely.</p><p>In the C files, no parsing of the surrounding code is done. The   context lies completely in the doc comments themselves, and the target   of the doc comment is determined by special meta keywords that are not   really part of the doc blocks, but rather modifiers that tell which
autodoc.git/traditional_manual/chapter_21.html:259:    *! ... */       /*! @endclass */       /*! @endmodule */   </pre><p></p>   <p>The <tt>@module</tt> and <tt>@class</tt> too keywords are to work like segment   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>   <p>To be considered one doc block, the comments must be separated only by   whitespace and <tt>\n</tt>, that is they have to be on adjacent lines   in the code. Each doc block in the Pike code has one or more targets;   the Pike entities (modules, classes, variables etc.) that the doc   block is documenting. The target of a doc comment is the coherent   block of declarations adjacent to (immediately before or after) it in   the code, without intervening blank lines. Examples:</p><p></p><pre>
autodoc.git/traditional_manual/chapter_21.html:433:    //! @endignore       //! To the parser, this function appears to be on the top level    int f() { ... }       //! @ignore    }    //! @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>   <li><p> The "what-are-we-documenting level" constructs; <tt>@decl</tt> for Pike files    and <tt>@module</tt>, <tt>@endmodule</tt>, <tt>@class</tt> and <tt>@endclass</tt>    on top of that for C files. These are the meta level tags covered in section a).</p></li>      <li><p> Inside-of-comment level constructs for documentation markup,    covered in sections b), c) and d).</p></li>   </ul><p>All markup can also be divided into categories based on their look   and semantics; there are three categories here (with examples):</p><ul>   <li><p> Grouping constructs that mark the opening/closing of a section of    some sort (<tt>@mapping/@endmapping, @dl/@enddl, @module/@endmodule</tt>).    Most of these not already covered by secion a) appear in b).</p></li>      <li><p> subdividers that break up an outer grouping construct into    subsections (<tt>@member, @item, @param</tt>)</p></li>      <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>   Keyword: @module   Legal for: C files only (neither needed nor legal for Pike files)   Arguments: (the last segment of) the module name (ie no "." allowed)   </pre></p><p>Example: To document the module <tt>Parser.XML</tt> module, you need two   consecutive module tags:</p><p></p><pre>    /*! @module Parser */    /*! @module XML */