Diff of autodoc.git/traditional_manual/chapter_21.html (585bd438360fca338de4fe4895694f9f34aa31a1 » f6a422df4113bcaa37e83b5e8e4d7c90e43af2e1)

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> - <h2 class='header'>21.1. Syntax</h2></dt> - <dd></dd><dt><h3 class='header'>21.1.1. Line orientation</h3></dt><dd>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:<pre> - //! @variable thisVariableNameIsSoLong@ - //!YouJustCantBelieveIt - </pre> - will appear to the parser as:<pre> - //! @variable thisVariableNameIsSoLongYouJustCantBelieveIt - </pre> - This is sometimes necessary because keywords that take parameters - expect all the parameters to appear on the same line and treat the end - of the line as the end of the parameter list.The character '\r' is also discarded. The same applies to all other - non-printable and control characters except for '\n' and '\t'.In text (see the nonterminal 'text' in the grammar at the end of this - file), a blank line with surrounding non-blank lines will give a - paragraph break. Thus:<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> - will generate the following XML:<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></dd><dt><h3 class='header'>21.1.2. Keywords</h3></dt><dd>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):<ol> - <li> 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.</li> - - <li> 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.</li> - - <li> 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.</li> - - <li> Short markup keywords <tt>[@ref{..@}, @i{..@}, ...]</tt> - These are used in the text to perform cosmetic tasks, for example - 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 <tt>@keyword{ and end with @}</tt>.</li> - - <li> 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 - <tt>@</tt> must still be quoted with <tt>@@</tt>. <tt><</tt> and <tt>></tt> must also be quoted unless - the intention really is to write XML. For example: - - <example> - //! He is so @xml{italic and @b{bold@}!@}!! - </example> - - will generate the following XML: - - <pre> - He is so italic and bold!!! - </pre></li> - </ol>NOTA BENE: Delimiter keywords (2) and block keywords (3) must stand - alone (with their parameters, if any) on one line.</dd><dt><h3 class='header'>21.1.3. Delimiter keyword grouping</h3></dt><dd>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:<pre> - //! @decl int dist(int x, int y) - //! Calculates the distance. - //! @param x - //! @param y - //! The coordinates of the vector. - </pre> - 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:<pre> - //! Error, can't group @note and @param: - //! @param x - //! @note - //! Don't use this function. At all. Ever. - </pre> - </dd><dt><h3 class='header'>21.1.4. Keyword parameters</h3></dt><dd>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:<ol> - <li> 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.</li> - - <li> Default parameter list syntax - The meaning of parameters is determined by the order in which they - appear, much like the arguments in a unix shell command line - hence - they are not named as in HTML or XML. Parameters are separated by - whitespace. If you wish to have a parameter string with whitespace in - it, you must surround the string with a pair of ' or ". When the - quoting character itself is in the string, a duplication is used to - quote it: - - <example> - //! @question "He is a ""swapper""?!" - </example> - - However, if your parameter contains only one of ' and ", then it is - smarter to choose the other one as the quouting character: - - <example> - //! @question 'He is a "swapper"?!' - </example> - - It is an error not to end a quote before the end of the line: - - <example> - //! @wrong "Aww, come on now, this worked fine in C64 basic! - </example> - - 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: - - <example> - //! @right "Oh, joy! Now I can make my parameters just as@ - //! long as I want them!" - </example> - - 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: - - <example> - //! @look "\n" - </example> - - The parameter will be a string with two characters, a backslash - followed by the letter n.</li> - </ol></dd><dt><h3 class='header'>21.1.5. Grammar</h3></dt><dd>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)<pre> - docblock: - metaline*, blockbody - - metaline: - start_of_line, white_space*, metakeyword, any_char_but_newline, - end_of_line - - blockbody: - section?, (delimiter+, section)*, delimiter? - - delimiter: - start_of_line, white_space*, delimiterkeyword, parameterlist, - end_of_line - - section: - (text|block)+ - - block: - blockbegin, blockbody, blockend - - blockbegin: - start_of_line, white_space*, blockkeyword, parameterlist, - end_of_line - - blockend: - start_of_line, white_space*, blockkeyword, white_space*, end_of_line - - parameterlist: - white_space*, (parameter, white_space+)* - - parameter: - qoutedparameter | any_char_but_white_space+ - - quotedparameter: - ('"', (any_char_but_new_line_or_" | '""'), '"') - | ('\'', (any_char_but_new_line_or_' | '\'\''), '\'') - - text: - (character|shortmarkup|xmlescape)+ - - xmlescape: - '@xml{', any_char_sequence_not_containing_@}, '@}' - - character: - any_char_but_@ | '@@' - - shortmarkup: - shortmarkupkeyword, '{', text, '@}' - - metakeyword, blockkeyword, delimiterkeyword, shortmarkupkeyword: - keyword - - keyword: - '@', alpha_char+ - - endblockkeyword: - '@end', alpha_char+ - - white_space: - ' ' | '\t' - </pre></dd> - <dt><a name='2'></a> - <h2 class='header'>21.2. Pike autodoc inlining</h2></dt> - <dd>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.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.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.</dd><dt><h3 class='header'>21.2.1. C files</h3></dt><dd>In C files, the doc comments look like:<pre> - /*! yadda yadda - *! yadda yadda yadda - */ - </pre> - 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.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.<pre> - /*! @module Foo - *! ... doc for the Foo module ... - *! ... */ - - /*! @decl int a() - *! ... doc for the method Foo.a() ... - *! .... */ - - /*! @class Bar - *! ... doc for the class Foo.Bar ... - *! ... */ - - /*! @decl mapping(string:string) userprefs() - *! ... doc for the method Foo.Bar->userprefs() ... - *! ... */ - - /*! @decl int a - *! @decl int b - *! ... doc for the variables Foo.Bar->a and Foo.Bar->b ... - *! ... */ - - /*! @endclass */ - - /*! @endmodule */ - </pre> - 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.</dd><dt><h3 class='header'>21.2.2. Pike files</h3></dt><dd>Doc comments look like:<pre> - //! yadda yadda yadda - //! yadda yadda - </pre> - 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:<pre> - //! Doc for alpha - int alpha() - { - return 4711; - } - - protected int undocumented; - - //! Error! This doc block has no destination! - - int beta; - //! Doc for beta - - //! Doc for gamma, delta, and epsilon - int gamma, delta; - float epsilon; - - //! Error here! - int zeta; - //! ambiguous which doc to associate with zeta. - - int eta; - //! Error here too! ambiguous which variable is documented. - int theta; - - //! Doc for two methods. This is so UGLY! We strongly recommend - //! using the decl keywords instead to accomplish this effect. - int methodOne() - { - ... - } - int methodTwo() - { - ... - } - - //! However, it can be useful sometimes, for really short methods: - int very_short() { return 4711; } - int even_shorter() { return 0; } - </pre> - 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:<pre> - //! Doc for the class - class CheeseMaker - { - //! You can even document inherits! - inherit Earth : earth; - - //! Doc for CheeseMaker->a() - int a() - { - ... - } - - void create(string s) { ... } - } - </pre> - 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:<pre> - class a() - { - //! @decl foo - //! ... doc for foo ... - } - </pre> - 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 <tt>{</tt>, like this:<pre> - 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; - } - </pre> - 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 <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:<pre> - //! @decl int a(int x) - //! @decl int b(int x) - //! Here is some doc for these functions.... - </pre> - is autodocwise equivalent to:<pre> - //! Here is some doc for these functions.... - int a(int x) - { - ..... - } - int b(int x) - { - ..... - } - </pre> - In 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 <tt>@decl</tt>'s must be methods that have the same name as the real - method:<pre> - //! @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) - { - .... - } - </pre> - The real method prototype is discarded in favour to the <tt>@decl</tt>'ed - variants, who will be shown in the documentation instead.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:<pre> - #ifdef MALE - int bertil() - #else - int berit() - #endif - { - ... body ... - } - </pre> - 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 - <tt>@ignore</tt>:<pre> - //! @ignore - - HERE_ARE_SOME_STRANGE_THINGS - #ifdef A - A - #endif - - //! @endignore - </pre> - 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:<pre> - //! @ignore - class C { - //! @endignore - - //! To the parser, this function appears to be on the top level - int f() { ... } - - //! @ignore - } - //! @endignore - </pre> - </dd> - <dt><a name='3'></a> - <h2 class='header'>21.3. Pike autodoc tags</h2></dt> - <dd>We have defined some different categories of markup, each with its own - semantics. Seen from the parser, there are two main construct levels:<ul> - <li> 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).</li> - - <li> Inside-of-comment level constructs for documentation markup, - covered in sections b), c) and d).</li> - </ul>All markup can also be divided into categories based on their look - and semantics; there are three categories here (with examples):<ul> - <li> 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).</li> - - <li> subdividers that break up an outer grouping construct into - subsections (<tt>@member, @item, @param</tt>)</li> - - <li> short text markup constructs that basically map to XML containers - (<tt>@i{...@}, @ref{...@}</tt>)</li> - </ul></dd><dt><h3 class='header'>21.3.1. Meta level tags</h3></dt><dd>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.<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>Example: To document the module <tt>Parser.XML</tt> module, you need two - consecutive module tags:<pre> - /*! @module Parser */ - /*! @module XML */ - </pre> - 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:<pre> - /*! @endmodule XML */ - /*! @endmodule Parser */ - </pre> - A <tt>@module</tt> keyword may also have a text child documenting the module - itself:<pre> - /*! @module Parser - *! - *! The common roof under which parsers of various kinds, such as - *! @[Parser.XML], @[Parser.Pike] and @[Parser.C] are housed. - */ - </pre> - 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 - <tt>predef::</tt> scope, as in:<pre> - /*! @module predef:: - *! @decl int equal(mixed a, mixed b) - *! This function checks if the values @[a] and @[b] are equal. - *! @endmodule - */ - </pre> - 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:<pre> - /*! @module lfun:: - *! @decl int(0..1) `!=(mixed arg1, mixed arg2, mixed ... extras) - *! The inequality operator. - *! @endmodule - */ - </pre> - 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.<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>>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 <tt>@module</tt> example above. The following - would trigger an error:<pre> - /*! @module Parser - *! @module XML */ - - /*! ... some autodoc comments ... */ - - /*! @endmodule Parser - *! @endmodule XML */ - </pre> - while the same example, ending in<pre> - /*! @endmodule - *! @endmodule */ - </pre> - would be considered legal.<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>Example: to document the <tt>Process.create_process</tt> class, you would use:<pre> - /*! @module Process - *! @class create_process */ - </pre> - And end the scope similar to <tt>@module</tt>:<pre> - /*! @endclass create_process - *! @endmodule Process */ - </pre> - Like <tt>@module</tt> tags, <tt>@class</tt> tags may be nested any number of levels - (when documenting subclasses to subclasses to subclasses to ...).<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>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 <tt>@endmodule</tt> above.<pre> - Keyword: @decl - Legal for: All source code (C and Pike files) - Arguments: (the last segment of) the identifier name (ie "." illegal) - </pre>The <tt>@decl</tt> keyword is used to target a specific (...more to come! :-)<pre> - - - - +--------------------------------------+ - | Pike autodoc markup - the XML format | - +--------------------------------------+ - - ====================================================================== - a) Introduction - ---------------------------------------------------------------------- - - When a piece of documentation is viewed in human-readable format, it - has gone through the following states: - - 1. Doc written in comments in source code (C or Pike). - - 2. A lot of smaller XML files, one for each source code file. - - 3. A big chunk of XML, describing the whole hierarchy. - - 4. A repository of smaller and more manageable XML files. - - 5. A HTML page rendered from one such file. - (Or a PDF file, or whatever). - - The transition from state 1 to state 2 is the extraction of - documentation from source files. There are several (well, at - least two) markup formats, and there are occasions where it is - handy to generate documentation automatically &c. This document - describes how a file in state 2 should be structured in order to - be handled correctly by subsequent passes and presented in a - consistent manner. - - ====================================================================== - b) Overall structure - ---------------------------------------------------------------------- - - Each source file adds some number of entities to the whole hierarchy. - It can contain a class or a module. It can contain an empty module, - that has its methods and members defined in some other source file, - and so on. Suppose we have a file containing documentation for the - class Class in the module Module. The XML skeleton of the file - would then be: - - <module name=""> - <module name="Module"> - <class name="Class"> - ... perhaps some info on inherits, members &c ... - <doc> - ... the documentation of the class Module.Class ... - </doc> - </class> - </module> - </module> - - The <module name=""> refers to the top module. That element, and its - child <module name="Module">, exist only to put the <class name="Class"> - in its correct position in the hierarchy. So we can divide the elements - in the XML file into two groups: skeletal elements and content elements. - - Each actual module/class/whatever in the Pike hierarchy maps to at most - one content element, however it can map to any number of skeletal elements. - For example, the top module is mapped to a skeletal element in each XML - file extracted from a single source file. To get from state 2 to state 3 - in the list above, all XML files are merged into one big. All the elements - that a module or class map to are merged into one, and if one of those - elements contains documentation (=is a content element), then that - documentation becomes a child of the merger of the elements. - - ====================================================================== - c) Grouping - ---------------------------------------------------------------------- - - Classes and modules always appear as <module> and <class> elements. - Methods, variables, constants &c, however, can be grouped in the - source code: - - //! Two variables: - int a; - int b; - - Even a single variable is considered as a group with one member. - Continuing the example in the previous section, suppose that Module.Class - has two member variables, a and b, that are documented as a group: - - <module name=""> - <module name="Module"> - <class name="Class"> - ... perhaps some info on inherits, members &c ... - - <docgroup homogen-type="variable"> - <variable name="a"><type><int/></type></variable> - <variable name="b"><type><int/></type></variable> - <doc> - ... documentation for Module.Class.a and Module.Class.b ... - </doc> - </docgroup> - - <doc> - ... the documentation of the class Module.Class ... - </doc> - </class> - </module> - </module> - - If all the children of a <docgroup> are of the same type, e.g. all are - <method> elements, then the <docgroup> has the attribute homogen-type - (="method" in the example). If all the children have identical name="..." - attributes, then the <docgroup> gets a homogen-name="..." attribute aswell. - - The <docgroup> has a <doc> child containing the docmentation for the other - children of the <docgroup>. An entity that cannot be grouped (class, module, - enum), has a <doc> child of its own instead. - - ====================================================================== - d) Pike entities - ---------------------------------------------------------------------- - - Pike entities - classes, modules, methods, variables, constants, &c, have some - things in common, and many parts of the xml format are the same for all of - these entities. All entities are represented with an XML element, namely one - of: - - <class> - <constant> - <enum> - <inherit> - <method> - <modifier> - <module> - <typedef> - <variable> - - The names speak for themselves, except: <modifier> which is used for modifier - ranges: - - //! Some variables: - protected final { - int x, y; - - string n; - } - - A Pike entity may also have the following properties: - - Name - Given as a name="..." attribute: - <variable name="i"> ... </variable> - - Modifiers - Given as a child element <modifiers>: - <variable name="i"> - <modifiers> - <optional/><protected/><private/> - </modifiers> - ... - </variable> - If there are no modifiers before the declaration of the entity, the - <modifiers> element can be omitted. - - Source position - Given as a child element <source-position>: - <variable name="i"> - <source-position file="/home/rolf/hejhopp.pike" first-line="12"/> - <modifiers> - <optional/><protected/><private/> - </modifiers> - ... - </variable> - The source position is the place in the code tree where the entity is - declared or defined. For a method, the attribute last-line="..." can be - added to <source-position> to give the range of lines that the method - body spans in the source code. - - And then there are some things that are specific to each of the types of - entities: - - <class> - All inherits of the class are given as child elements <inherit>. If there - is doc for the inherits, the <inherit> is repeated inside the appropriate - <docgroup>: - - class Bosse { - inherit "arne.pike" : Arne; - inherit Benny; - - //! Documented inherit - inherit Sven; - } - - <class name="Bosse"> - <inherit name="Arne"><source-position ... /> - <classname>"arne.pike"</classname></inherit> - <inherit><source-position ... /> - <classname>Benny</classname></inherit> - <inherit><source-position ... /> - <classname>Sven</classname></inherit> - <docgroup homogen-type="inherit"> - <doc> - <text>Documented inherit</text> - </doc> - <inherit><source-position ... /> - <classname>Sven</classname></inherit> - </docgroup> - ... - </class> - - <constant> - Only has a name. The element is empty (or has a <source-position> child.) - - <enum> - Works as a container. Has a <doc> child element with the documentation of - the enum itself, and <docgroup> elements with a <constant> for each enum - constant. So: - - enum E - //! enum E - { - //! Three constants: - a, b, c, - - //! One more: - d - } - - becomes: - - <enum name="E"> - <doc><text>enum E</text></doc> - <docgroup homogen-type="constant"> - <doc><text>Three constants:</text></doc> - <constant name="a"/> - <constant name="b"/> - <constant name="c"/> - </docgroup> - <docgroup homogen-name="d" homogen-type="constant"> - <doc><text>One more:</text></doc> - <constant name="d"/> - </docgroup> - </enum> - - Both the <enum> element and the <constant> elements could have - <source-position> children, of course. - - <inherit> - The name="..." attribute gives the name after the colon, if any. The name - of the inherited class is given in a <classname> child. If a file name is - used, the class name is the file name surrounded by quotes (see <class>). - - <method> - The arguments are given inside an <arguments> child. Each argument is - given as an <argument name="..."> element. Each <argument> has a <type> - child, with the type of the argument. The return type of the method is - given inside a <returntype> container: - - int a(int x, int y); - - <method name="a"> - <arguments> - <argument name="x"><type><int/></type></argument> - <argument name="y"><type><int/></type></argument> - </arguments> - <returntype><int/></returntype> - </method> - - <modifier> - Works as a container ... ??? - - <module> - Works just like <class>. - - <typedef> - The type is given in a <type> child: - - typedef float Boat; - - <typedef name="Boat"><type><float/></type></typedef> - - <variable> - The type of the variable is given in a <type> child: - - int x; - - <variable name="x"><type><int/></type></variable> - - ====================================================================== - e) Pike types - ---------------------------------------------------------------------- - - Above we have seen the types int and float represented as <int/> and <float/>. - Some of the types are complex, some are simple. The simpler types are just on - the form <foo/>: - - <float/> - <mixed/> - <program/> - <string/> - <void/> - - The same goes for mapping, array, function, object, multiset, &c that have - no narrowing type qualification: <mapping/>, <array/>, <function/> ... - - The complex types are represented as follows: - - array - If the type of the elements of the array is specified it is given in a - <valuetype> child element: - - array(int) - - <array><valuetype><int/></valuetype></array> - - function - The types of the arguments and the return type are given (the order - of the <argtype> elements is significant, of course): - - function(int, string: mixed) - - <function> - <argtype><int/></argtype> - <argtype><string/></argtype> - <returntype><mixed/></returntype> - </function> - - int - An int type can have a min and/or max value. The values can be numbers or - identifiers: - - int(0..MAX) - - <int><min>0</min><max>MAX</max></int> - - mapping - The types of the indices and values are given: - - mapping(int:int) - - <mapping> - <indextype><int/></indextype> - <valuetype><int/></valuetype> - - multiset - The type of the indices is given: - - multiset(string) - - <multiset> - <indextype><string/></indextype> - </multiset> - - object - If the program/class is specified, it is given as the text child of - the <object> element: - - object(Foo.Bar.Ippa) - - <object>Foo.Bar.Ippa</object> - - Then there are two special type constructions. A disjunct type is written - with the <or> element: - - string|int - - <or><string/><int/></or> - - An argument to a method can be of the varargs type: - - function(string, mixed ... : void) - - <function> - <argtype><string/></argtype> - <argtype><varargs><mixed/></varargs></argtype> - <returntype><void/></returntype> - </function> - - ====================================================================== - f) Other XML tags - ---------------------------------------------------------------------- - - p - Paragraph. - - i - Italic. - - b - Bold. - - tt - Terminal Type. - - pre - Preformatted text. - - code - Program code. - - image - An image object. Contains the original file path to the image. Has the - optional attributes width, height and file, where file is the path to - the normalized-filename file. - - ====================================================================== - g) XML generated from the doc markup - ---------------------------------------------------------------------- - - The documentation for an entity is put in a <doc> element. The <doc> element - is either a child of the element representing the entity (in the case of - <class>, <module>, <enum>, or <modifiers>) or a child of the <docgroup> that - contains the element representing the entity. - - The doc markup has two main types of keywords. Those that create a container - and those that create a new subsection within a container, implicitly closing - the previous subsection. Consider e.g.: - - //! @mapping - //! @member int "ip" - //! The IP# of the host. - //! @member string "address" - //! The name of the host. - //! @member float "latitude" - //! @member float "longitude" - //! The coordinates of its physical location. - //! @endmapping - - Here @mapping and @endmapping create a container, and each @member start a - new subsection. The two latter @member are grouped together and thus they - form ONE new subsection together. Each subsection is a <group>, and the - <group> has one or more <member> children, and a <text> child that contains - the text that describes the <member>s: - - <mapping> - <group> - <member><type><int/></type><index>"ip"</index></member> - <text> - The IP# of the host. - </text> - </group> - <group> - <member><type><string/></type><index>"address"</index></member> - <text> - The name of the host. - </text> - </group> - <group> - <member><type><float/></type><index>"latitude"</index></member> - <member><type><float/></type><index>"longitude"</index></member> - <text> - The coordinates of its physical location. - </text> - </group> - </mapping> - - Inside a <text> element, there can not only be text, but also a nested level - of, say @mapping - @endmapping. In that case, the <mapping> element is put in - the document order place as a sibling of the that contain the text: - - //! @mapping - //! @member mapping "nested-mapping" - //! A mapping inside the mapping: - //! @mapping - //! @member string "zip-code" - //! The zip code. - //! @endmapping - //! And some more text ... - //! @endmapping - - becomes: - - <mapping> - <group> - <member><type><mapping/></type><index>"nested-mapping"</index></member> - <text> - A mapping inside the mapping: - <mapping> - <group> - <member><type><string/></type><index>"zip-code"</index></member> - <text> - The zip code. - </text> - </group> - </mapping> - And some more text ... - </text> - </group> - </mapping> - - Inside the elements, there may also be some more "layout-ish" tags like - , <code>, <tt>, , needed to make the text more readable. Those tags are - expressed as @i{ ... @} in the doc markup. However there are no . A - paragraph break is done by ending the and beginning a new. A is - inserted for each sequence of blank lines in the doc markup: - - //! First paragraph. - //! - //! Second paragraph. - //! - //! - - becomes: - - First paragraph.Second paragraph. - - Note that the text is trimmed from leading and ending whitespaces, and there - are never any empty elements. - - In the example above the keyword `@mapping' translated into <mapping>, whereas - the keyword `@member string "zip-code"' translated into: - <member><type><string/></type><index>"zip-code"</index></member> - - The translation of keyword->XML is done differently for each keyword. How it - is done can be seen in lib/modules/Tools.pmod/AutoDoc.pmod/DocParser.pmod. Most - keywords just interpret the arguments as a space-separated list, and put their - values in attributes to the element. In some cases (such as @member) though, - some more intricate parsing must be done, and the arguments may be complex - (like Pike types) and are represented as child elements of the element. - - ====================================================================== - h) Top level sections of different Pike entities. - ---------------------------------------------------------------------- - - In every doc comment there is an implicit "top container", and subsections can - be opened in it. E.g.: - - //! A method. - //! @param x - //! The horizontal coordinate. - //! @param y - //! The vertical coordinate. - //! @returns - //! Nothing :) - void foo(int x, int y) - - becomes: - - <docgroup homogen-name="foo" homogen-type="method"> - <doc> - <text>A method.</text> - <group> - <param name="x"/> - <text>The horizontal coordinate.</text> - </group> - <group> - <param name="y"/> - <text>The vertical coordinate.</text> - </group> - <group> - <returns/> - <text>Nothing :)</text> - </group> - </doc> - <method name="foo"> - ...... - </method> - </docgroup> - - Which "top container" subsections are allowed depends on what type of entity is - documented: - - ALL - <bugs/> - <deprecated> ... </deprecated> - <example/> - <note/> - <seealso/> - - <method> - <param name="..."/> - <returns/> - <throws/> - </pre></dd></dl></body></html> + <body><dl><dt><h1 class='header'>21. Pike BNF</h1></dt><dd><dl> + <dt><a href='index.html'>Table of Contents</a></dt> + <dt><a href='chapter_1.html'>1. Introduction</a></dt> + <dd><a href='chapter_1.html#1'>1.1. Overview</a></dd> + <dd><a href='chapter_1.html#2'>1.2. The history of Pike</a></dd> + <dd><a href='chapter_1.html#3'>1.3. A comparison with other languages</a></dd> + <dd><a href='chapter_1.html#4'>1.4. What is Pike</a></dd> + <dd><a href='chapter_1.html#5'>1.5. Pike License</a></dd> + <dt><a href='chapter_2.html'>2. Control Structures</a></dt> + <dd><a href='chapter_2.html#1'>2.1. Conditions</a></dd> + <dd><a href='chapter_2.html#2'>2.2. Loops</a></dd> + <dd><a href='chapter_2.html#3'>2.3. Breaking out of loops</a></dd> + <dt><a href='chapter_3.html'>3. Operators</a></dt> + <dd><a href='chapter_3.html#1'>3.1. Arithmetic operators</a></dd> + <dd><a href='chapter_3.html#2'>3.2. Comparison operators</a></dd> + <dd><a href='chapter_3.html#3'>3.3. Logical operators</a></dd> + <dd><a href='chapter_3.html#4'>3.4. Bitwise/set operators</a></dd> + <dd><a href='chapter_3.html#5'>3.5. Indexing</a></dd> + <dd><a href='chapter_3.html#6'>3.6. The assignment operators</a></dd> + <dd><a href='chapter_3.html#7'>3.7. The rest of the operators</a></dd> + <dd><a href='chapter_3.html#8'>3.8. Operator precedence</a></dd> + <dd><a href='chapter_3.html#9'>3.9. Operator functions</a></dd> + <dt><a href='chapter_4.html'>4. Preprocessor</a></dt> + <dd><a href='chapter_4.html#1'>4.1. Charset Heuristics</a></dd> + <dd><a href='chapter_4.html#2'>4.2. Code Normalization</a></dd> + <dd><a href='chapter_4.html#3'>4.3. Defines and Macros</a></dd> + <dd><a href='chapter_4.html#4'>4.4. Preprocessor Directives</a></dd> + <dd><a href='chapter_4.html#5'>4.5. Predefined defines</a></dd> + <dd><a href='chapter_4.html#6'>4.6. Test functions</a></dd> + <dt><a href='chapter_5.html'>5. Special Functions</a></dt> + <dd><a href='chapter_5.html#1'>5.1. sscanf</a></dd> + <dd><a href='chapter_5.html#2'>5.2. catch</a></dd> + <dd><a href='chapter_5.html#3'>5.3. gauge</a></dd> + <dd><a href='chapter_5.html#4'>5.4. typeof</a></dd> + <dt><a href='chapter_6.html'>6. Hilfe</a></dt> + <dd><a href='chapter_6.html#1'>6.1. Basic operations</a></dd> + <dd><a href='chapter_6.html#2'>6.2. Commands</a></dd> + <dd><a href='chapter_6.html#3'>6.3. Bugs and possible improvements</a></dd> + <dt><a href='chapter_7.html'>7. LFUN</a></dt> + <dt><a href='chapter_8.html'>8. I/O</a></dt> + <dt><a href='chapter_9.html'>9. Specific Datatype Modules</a></dt> + <dt><a href='chapter_10.html'>10. Parsers</a></dt> + <dt><a href='chapter_11.html'>11. Image Module</a></dt> + <dt><a href='chapter_12.html'>12. Protocols</a></dt> + <dt><a href='chapter_13.html'>13. Database Access</a></dt> + <dt><a href='chapter_14.html'>14. Graphic User Interface</a></dt> + <dt><a href='chapter_15.html'>15. 3D Vector Graphics</a></dt> + <dt><a href='chapter_16.html'>16. The rest</a></dt> + <dt><a href='chapter_17.html'>17. Backward Compatibility</a></dt> + <dd><a href='chapter_17.html#1'>17.1. Pike 8.0</a></dd> + <dd><a href='chapter_17.html#2'>17.2. Pike 7.8</a></dd> + <dd><a href='chapter_17.html#3'>17.3. Pike 7.6 and earlier</a></dd> + <dt><a href='chapter_18.html'>18. Writing Pike Modules</a></dt> + <dd><a href='chapter_18.html#1'>18.1. Writing Modules in Pike</a></dd> + <dd><a href='chapter_18.html#2'>18.2. Writing Modules in C</a></dd> + <dd><a href='chapter_18.html#3'>18.3. Special Module Variables and functions</a></dd> + <dt><a href='chapter_19.html'>19. Pike Test Suite</a></dt> + <dd><a href='chapter_19.html#1'>19.1. Running Tests</a></dd> + <dd><a href='chapter_19.html#2'>19.2. Writing New Tests</a></dd> + <dt><a href='chapter_20.html'>20. Pike AutoDoc markup</a></dt> + <dd><a href='chapter_20.html#1'>20.1. Syntax</a></dd> + <dd><a href='chapter_20.html#2'>20.2. Pike autodoc inlining</a></dd> + <dd><a href='chapter_20.html#3'>20.3. Pike autodoc tags</a></dd> + <dt><a href='chapter_21.html'>21. Pike BNF</a></dt> + </dl></dd></dl></body></html>

autodoc.git / traditional_manual / chapter_21.html