pike.git / refdoc / chapters / autodoc.xml

version» Context lines:

pike.git/refdoc/chapters/autodoc.xml:1:   <chapter title='Pike AutoDoc markup'>      <section title='Syntax'>      <subsection title="Line orientation">      <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 @ on the line - indicates that it continues on the next line. The @ and the newline + 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>      <example>    //! @variable thisVariableNameIsSoLong@    //!YouJustCantBelieveIt   </example>      <p>will appear to the parser as:</p>      <example>
pike.git/refdoc/chapters/autodoc.xml:43:   <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>      </subsection>      <subsection title="Keywords">    - <p>Keywords always begin with an at-sign: @. A @ is quoted by writing two - of them: @@. There are four types of keywords (the keywords in []'s + <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 [@decl, @class, @endclass, @module and @endmodule] + <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>    - <li><p> Delimiter keywords [@param, @member, @item, @note, ...] + <li><p> Delimiter keywords <tt>[@param, @member, @item, @note, ...]</tt>    Must stand alone on one line, preceded only by whitespace. These are    keywords that begin a section inside their block. They have no end    marker, but rather the section ends when the next delimiter keyword    on the same level is found. Can have parameters.</p></li>    - <li><p> Block/endblock keywords [@dl - @enddl, @mapping - @endmapping, ...] + <li><p> Block/endblock keywords <tt>[@dl - @enddl, @mapping - @endmapping, ...]</tt>    Must stand alone on one line, preceded only by whitespace. These open    or close a block. If a block is started with @foo, it must end with a    matching @endfoo. The lines inside the block can be divided into    sections by using delimiter keywords. The start keyword can have    parameters, but the corresponding end keyword can not.</p></li>    - <li><p> Short markup keywords [@ref{..@}, @i{..@}, ...] + <li><p> Short markup keywords <tt>[@ref{..@}, @i{..@}, ...]</tt>    These are used in the text to perform cosmetic tasks, for example -  changing text to italic (@i), teletype(@tt) or marking a word as a -  reference to a pike entity (@ref). They can be nested, but a short +  changing text to italic (<tt>@i</tt>), teletype(<tt>@tt</tt>) or marking a word as a +  reference to a pike entity (<tt>@ref</tt>). They can be nested, but a short    markup keyword can not contain a keyword of types 1-3. They begin -  with @keyword{ and end with @}.</p></li> +  with <tt>@keyword{ and end with @}</tt>.</p></li>    - <li><p> The magic keyword @xml{ ... @} + <li><p> The magic keyword <tt>@xml{ ... @}</tt>    This is a special keyword that provides an escape to XML. All ordinary    text inside it is passed unquoted to the output. However, the short    markup keywords are still valid and may be used inside it, and thus -  @ must still be quoted with @@. &lt; and &gt; must also be quoted unless +  <tt>@</tt> must still be quoted with <tt>@@</tt>. <tt>&lt;</tt> and <tt>&gt;</tt> must also be quoted unless    the intention really is to write XML. For example:</p>       <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;!!!
pike.git/refdoc/chapters/autodoc.xml:113:   consecutive lines. For example, when documenting a method:</p>      <example>    //! @decl int dist(int x, int y)    //! Calculates the distance.    //! @param x    //! @param y    //! The coordinates of the vector.   </example>    - <p>Above, the two @param's x and y are grouped together and share the + <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>      <example>    //! Error, can't group @note and @param:    //! @param x    //! @note    //! Don't use this function. At all. Ever.   </example>      </subsection>      <subsection title="Keyword parameters">    - <p>After the leading @keyword (that may be preceded only by whitespace) + <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>   
pike.git/refdoc/chapters/autodoc.xml:165:   <example>    //! @question 'He is a "swapper"?!'   </example>       <p>It is an error not to end a quote before the end of the line:</p>      <example>    //! @wrong "Aww, come on now, this worked fine in C64 basic!   </example>    -  <p>If a quoted parameter is too long to fit in one line, use the @ at +  <p>If a quoted parameter is too long to fit in one line, use the <tt>@</tt> at    the end of the line to merge it with the following:</p>      <example>    //! @right "Oh, joy! Now I can make my parameters just as@    //! long as I want them!"   </example>       <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>
pike.git/refdoc/chapters/autodoc.xml:191:    <p>The parameter will be a string with two characters, a backslash    followed by the letter n.</p></li>   </ol>      </subsection>         <subsection title="Grammar">      <p>Here comes a BNF-ish grammar for documentation blocks. Note that - before the parsing of the block, all lines ending with a @ will be + 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   
pike.git/refdoc/chapters/autodoc.xml:290:   <subsection title="C files">      <p>In C files, the doc comments look like:</p>      <example>    /*! yadda yadda    *! yadda yadda yadda    */   </example>    - <p>Note that only lines that start with *! count, so above are only two - doc lines. Any whitespace before the leading *! is skipped, so that + <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   Pike entity the doc is about.</p>      <example>    /*! @module Foo
pike.git/refdoc/chapters/autodoc.xml:327:    /*! @decl int a    *! @decl int b    *! ... doc for the variables Foo.Bar-&gt;a and Foo.Bar-&gt;b ...    *! ... */       /*! @endclass */       /*! @endmodule */   </example>    - <p>The @module and @class too keywords are to work like segment - directives in assembler source files. That is, you can have "@module - foo" in several C files, if the module source is spread over multiple + <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>      </subsection>      <subsection title="Pike files">      <p>Doc comments look like:</p>      <example>    //! yadda yadda yadda    //! yadda yadda   </example>      <p>To be considered one doc block, the comments must be separated only by - whitespace and _one_ "\n", that is they have to be on adjacent lines + whitespace and <em>one</em> <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>      <example>    //! Doc for alpha    int alpha()    {
pike.git/refdoc/chapters/autodoc.xml:394:    int methodTwo()    {    ...    }       //! However, it can be useful sometimes, for really short methods:    int very_short() { return 4711; }    int even_shorter() { return 0; }   </example>    - <p>In Pike files, you can not use @class or @module to tell which module + <p>In Pike files, you can not use <tt>@class</tt> or <tt>@module</tt> to tell which module   or class you are in. To document a class, you simply write:</p>      <example>    //! Doc for the class    class CheeseMaker    {    //! You can even document inherits!    inherit Earth : earth;       //! Doc for CheeseMaker-&gt;a()    int a()    {    ...    }       void create(string s) { ... }    }   </example>    - <p>The parser will automatically identify a() as a member method of the - class CheeseMaker, and will detect that Earth is inherited by - CheeseMaker. If a class has no documentation comment, it's internals + <p>The parser will automatically identify <tt>a()</tt> as a member method of the + class <tt>CheeseMaker</tt>, and will detect that <tt>Earth</tt> is inherited by + <tt>CheeseMaker</tt>. If a class has no documentation comment, it's internals   will not be examined, thus it is an error if a class contains   documentation comments but is itself undocumented:</p>      <example>    class a()    {    //! @decl foo    //! ... doc for foo ...    }   </example>      <p>A special inlining case is that of functions and classes. When documenting   these, the doc comment can be put between the head of the function/class, - and the opening "{", like this:</p> + and the opening <tt>{</tt>, like this:</p>      <example>    class Roy    //! Documentation for Roy    {    ....    }       int un_randomize(int x)    //! This function takes a random number, and transforms it into    //! a predictable number.    {    return x = 4711;    }   </example>      <p>If a doc block is the first in a file, and it has no target, then it   is treated as doc for the file (or rather: the module/class that the   file compiles into) itself. In any other case it is an error to have a - targetless doc block. A target can also be set with the @decl meta - keyword. If a doc comment begins with some @decl keywords, these - @decl's act just like real declarations standing next to the doc. + targetless doc block. A target can also be set with the <tt>@decl</tt> meta + keyword. If a doc comment begins with some <tt>@decl</tt> keywords, these + <tt>@decl</tt>'s act just like real declarations standing next to the doc.   Thus:</p>      <example>    //! @decl int a(int x)    //! @decl int b(int x)    //! Here is some doc for these functions....   </example>      <p>is autodocwise equivalent to:</p>   
pike.git/refdoc/chapters/autodoc.xml:475:    int a(int x)    {    .....    }    int b(int x)    {    .....    }   </example>    - <p>In _one_ case it is legal to have both an adjacent declaration and - the @decl keyword at the block beginning. That is when you document + <p>In <em>one</em> case it is legal to have both an adjacent declaration and + the <tt>@decl</tt> keyword at the block beginning. That is when you document   "polymorph" methods. Then the adjacent declaration must be a method, - and all @decl's must be methods that have the same name as the real + and all <tt>@decl</tt>'s must be methods that have the same name as the real   method:</p>      <example>    //! @decl float cube(float x)    //! @decl int cube(int x)    //! Gives x**3.    //! @param x    //! The number to cube.    int|float cube(int|float x)    {    ....    }   </example>    - <p>The real method prototype is discarded in favour to the @decl'ed + <p>The real method prototype is discarded in favour to the <tt>@decl</tt>'ed   variants, who will be shown in the documentation instead.</p>    - <p>One problem that is unsolved so far is how to handle #if .. #else .. - #endif constructions. The approach so far has been to ignore + <p>One problem that is unsolved so far is how to handle <tt>#if .. #else .. + #endif</tt> constructions. The approach so far has been to ignore   preprocessor directives totally. For example, the parser does not   handle:</p>      <example>    #ifdef MALE    int bertil()    #else    int berit()    #endif    {    ... body ...    }   </example>      <p>It a portion of the code is unextractable because it contains too much   preprocessor macros and stuff, you can make the extractor skip it by using - @ignore:</p> + <tt>@ignore</tt>:</p>      <example>    //! @ignore       HERE_ARE_SOME_STRANGE_THINGS    #ifdef A    A    #endif       //! @endignore   </example>    - <p>All @ignore-@endignore sections of the file are removed before any extraction - is done, so they can cross class boundaries and the like. You can nest @ignore - inside eachother. Another application for @ignore is to hide actual class + <p>All <tt>@ignore-@endignore</tt> sections of the file are removed before any extraction + is done, so they can cross class boundaries and the like. You can nest <tt>@ignore</tt> + inside eachother. Another application for <tt>@ignore</tt> is to hide actual class   boundaries from the extractor:</p>      <example>    //! @ignore    class C {    //! @endignore       //! To the parser, this function appears to be on the top level    int f() { ... }   
pike.git/refdoc/chapters/autodoc.xml:554:      </subsection>   </section>      <section title="Pike autodoc tags">      <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; @decl for Pike files -  and @module, @endmodule, @class and @endclass on top of that for C -  files. These are the meta level tags covered in section a).</p></li> + <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 (@mapping/@endmapping, @dl/@enddl, @module/@endmodule). +  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 (@member, @item, @param)</p></li> +  subsections (<tt>@member, @item, @param</tt>)</p></li>      <li><p> short text markup constructs that basically map to XML containers -  (@i{...@}, @ref{...@})</p></li> +  (<tt>@i{...@}, @ref{...@}</tt>)</p></li>   </ul>      <subsection title="Meta level tags">      <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 Parser.XML module, you need two + <p>Example: To document the module <tt>Parser.XML</tt> module, you need two   consecutive module tags:</p>      <example>    /*! @module Parser */    /*! @module XML */   </example>    - <p>A @module keyword sets the scope of documentation comments following - it. @module tags nest, as shown in the example above, and must be + <p>A <tt>@module</tt> keyword sets the scope of documentation comments following + it. <tt>@module</tt> tags nest, as shown in the example above, and must be   ended with a matching number of @endmodule tags, as in:</p>      <example>    /*! @endmodule XML */    /*! @endmodule Parser */   </example>    - <p>A @module keyword may also have a text child documenting the module + <p>A <tt>@module</tt> keyword may also have a text child documenting the module   itself:</p>      <example>    /*! @module Parser    *!    *! The common roof under which parsers of various kinds, such as    *! @[Parser.XML], @[Parser.Pike] and @[Parser.C] are housed.    */   </example>    - <p>There are two special @module targets available; the "predef::" module - and the "lfun::" module. The predef:: module, although more of a scope + <p>There are two special @module targets available; the <tt>predef::</tt> module + and the <tt>lfun::</tt> module. The <tt>predef::</tt> module, although more of a scope   than a module, contains the definitions for all methods in Pike's - predef:: scope, as in:</p> + <tt>predef::</tt> scope, as in:</p>      <example>   /*! @module predef::    *! @decl int equal(mixed a, mixed b)    *! This function checks if the values @[a] and @[b] are equal.    *! @endmodule    */   </example>    - <p>The "lfun::" module scope does not legally exist in Pike, but it + <p>The <tt>lfun::</tt> module scope does not legally exist in Pike, but it   houses the docs for all lfuns (the virtual methods for fulfilling the   Pike object API). An example:</p>      <example>   /*! @module lfun::    *! @decl int(0..1) `!=(mixed arg1, mixed arg2, mixed ... extras)    *! The inequality operator.    *! @endmodule    */   </example>    - <p>This also means that referencing (via @ref{...@} or @[...]) the lfun - documentation strings can be done using @[lfun::`!=] and the like, as - can predefs via @[predef::sort()] et cetera.</p> + <p>This also means that referencing (via <tt>@ref{...@}</tt> or <tt>@[...]</tt>) the lfun + documentation strings can be done using <tt>@[lfun::`!=]</tt> and the like, as + can predefs via <tt>@[predef::sort()]</tt> et cetera.</p>      <p><pre>   Keyword: @endmodule   Legal for: C files only (neither needed nor legal for Pike files)   Arguments: (the last segment of) the module name (optional)   </pre>></p>    - <p>When the optional argument to @endmodule is given (for code clarity), + <p>When the optional argument to <tt>@endmodule</tt> is given (for code clarity),   the extractor will verify that the module scope you close was indeed - the one you opened, as in the @module example above. The following + the one you opened, as in the <tt>@module</tt> example above. The following   would trigger an error:</p>      <example>    /*! @module Parser    *! @module XML */       /*! ... some autodoc comments ... */       /*! @endmodule Parser    *! @endmodule XML */
pike.git/refdoc/chapters/autodoc.xml:683:   </example>      <p>would be considered legal.</p>      <p><pre>   Keyword: @class   Legal for: C files only (neither needed nor legal for Pike files)   Arguments: (the last segment of) the class name (ie no "." allowed)   </pre></p>    - <p>Example: to document the Process.create_process class, you would use:</p> + <p>Example: to document the <tt>Process.create_process</tt> class, you would use:</p>      <example>    /*! @module Process    *! @class create_process */   </example>    - <p>And end the scope similar to @module:</p> + <p>And end the scope similar to <tt>@module</tt>:</p>      <example>    /*! @endclass create_process    *! @endmodule Process */   </example>    - <p>Like @module tags, @class tags may be nested any number of levels + <p>Like <tt>@module</tt> tags, <tt>@class</tt> tags may be nested any number of levels   (when documenting subclasses to subclasses to subclasses to ...).</p>      <p><pre>   Keyword: @endclass   Legal for: C files only (neither needed nor legal for Pike files)   Arguments: (the last segment of) the class name (optional)   </pre></p>    - <p>When the optional argument to @endclass is given (for code clarity), + <p>When the optional argument to <tt>@endclass</tt> is given (for code clarity),   the extractor will verify that the class scope you close was indeed - the one you opened, just as with @endmodule above.</p> + the one you opened, just as with <tt>@endmodule</tt> above.</p>      <p><pre>   Keyword: @decl   Legal for: All source code (C and Pike files)   Arguments: (the last segment of) the identifier name (ie "." illegal)   </pre></p>    - <p>The @decl keyword is used to target a specific (...more to come! :-)</p> + <p>The <tt>@decl</tt> keyword is used to target a specific (...more to come! :-)</p>      </subsection>   </section>      <p><pre>             +--------------------------------------+    | Pike autodoc markup - the XML format |