pike.git / refdoc / keywords.txt

version» Context lines:

pike.git/refdoc/keywords.txt:1: - This document describes the keywords recognized by the AutoDoc parser, and their - intended use. + This document describes the keywords recognized by the AutoDoc parser, + and their intended use.    - ================================================================================ + ===============================================================================       META KEYWORDS    - ================================================================================ + ===============================================================================      Keyword: @appears   Description: Tell where the documentation for an item should be shown. -  Gives the full new name of the item. Must be placed first in -  the block, or immediately after any @module, @class, or @decl's. +  Gives the full new name of the item. Must be placed +  first in the block, or immediately after any @module, +  @class, or @decl's.   Arguments: <name> [, type]    Where: -  <name> is an "absolute" name with identifiers separated by dots. -  It can also be prefixed by 'scope::' where scope is one of -  the valid scope modules. -  [type] is either "class" or "module" depending on whether the -  target item should appear as a class or a module. When not -  present, the choice will be governed by the item's type, as -  detected by the extractor. Overriding this is only needed for -  odd special cases such as a module.pmod containing e g: +  <name> is an "absolute" name with identifiers +  separated by dots. It can also be prefixed by +  'scope::' where scope is one of the valid scope +  modules. +  [type] is either "class" or "module" depending on +  whether the target item should appear as a class or +  a module. When not present, the choice will be +  governed by the item's type, as detected by the +  extractor. Overriding this is only needed for odd +  special cases such as a module.pmod containing e g:    static class _Foo {...};    _Foo Foo = _Foo();   Children: -   Groups with: -   Examples: //! @appears predef::stat    //! This function is globally visible.    array stat() {    // function body    }    - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @belongs - Description: Tell where the documentation for an item should be shown. Gives -  the name of the new parent module or parent class. + Description: Tell where the documentation for an item should be +  shown. Gives the name of the new parent module or parent +  class.   Arguments: <name>    Where: -  <name> is an "absolute" name with identifiers separated by dots. -  It can also be prefixed by 'scope::' where scope is one of -  the valid scope modules. +  <name> is an "absolute" name with identifiers +  separated by dots. It can also be prefixed by +  'scope::' where scope is one of the valid scope +  modules.   Children: -   Groups with: -   Examples:    //! @decl int func()    //! @belongs AnotherModule    - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @class - Description: Declare and enter a new scope for a class. Only in C mode. Until -  an @endclass is found, all declarations will be regarded as -  children of the class. + Description: Declare and enter a new scope for a class. Only in C +  mode. Until an @endclass is found, all declarations will +  be regarded as children of the class. +    Arguments: <name>    Where: -  <name> is a valid Pike identifier. Not the "absolute" name -  with dots. +  <name> is a valid Pike identifier. Not the "absolute" +  name with dots. +    Children: Documentation for the class, or empty.   Groups with: -   Examples:    /*! @class Arne    *! A class with a Swedish name. */    - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @decl - Description: Declare a Pike entity and state that the current documentation -  block "is about" that entity. If the documentation block is bound -  to a Pike entity by adjacency (if it is a Pike file being -  extracted), then @decl is allowed iff: +  + Description: Declare a Pike entity and state that the current +  documentation block "is about" that entity. If the +  documentation block is bound to a Pike entity by +  adjacency (if it is a Pike file being extracted), then +  @decl is allowed iff:    1. The Pike entity in the adjacent code is one method. -  2. All @decl's in the block are methods with the same name as -  that method. (look at the last example below) +  2. All @decl's in the block are methods with the same +  name as that method. (look at the last example +  below)   Arguments: <declaration>    Where: -  <declaration> is a valid Pike declaration. A trailing ";" is -  optional. - Children: Documentation for the entity. After all @decl's may follow one of -  @appears or @belongs. +  <declaration> is a valid Pike declaration. A trailing +  ";" is optional. + Children: Documentation for the entity. After all @decl's may follow +  one of @appears or @belongs.   Groups with: @decl   Examples:    //! @decl void explode(string victim);    //! @decl float root(float x)    //! @decl mapping(string:string) arguments;    //! Doc for these three disparate things.       //! @decl float cube(float f)    //! @decl int cube(int i)    //! This is how to document a "polymorph" function.    float|int cube(float|int x) { /* body */ }    - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @endclass   Description: Leave the class scope entered by @class.   Arguments: [name]    Where: -  [name] if present, must be the same as the argument to @class. +  [name] if present, must be the same as the argument to +  @class.   Children:   Groups with: -   Examples:    /*! @endclass Reinhold */    - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @endmodule   Description: Leave the module scope entered by @module   Arguments: [name]    Where: -  [name] if present, must be the same as the argument to @module. +  [name] if present, must be the same as the argument to +  @module.   Children: -   Groups with: -   Examples:    /*! @endmodule Roine */    - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @endnamespace - Description: Leave the namespace entered by @namespace. -  Symbols defined outside a namespace will be defined in -  the default namespace "predef::". + Description: Leave the namespace entered by @namespace. Symbols +  defined outside a namespace will be defined in the +  default namespace "predef::".   Arguments: [name]    Where:    [name] if present, must be the same as the argument to    @namespace.   Children: -   Groups with: -   Examples:    /*! @endnamespace lfun:: */    - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @module - Description: Declare and enter a new scope for a module. Only in C mode. Until -  an @endmodule is found, all declarations will be regarded as -  children of the module. + Description: Declare and enter a new scope for a module. Only in C +  mode. Until an @endmodule is found, all declarations +  will be regarded as children of the module.   Arguments: <name>    Where: -  <name> is a valid Pike identifier. Not the "absolute" name -  with dots. +  <name> is a valid Pike identifier. Not the "absolute" +  name with dots.   Children: Documentation for the module, or empty.   Groups with: -   Examples:    /*! @module Kenny    *! A module with a Norwegian name. */    - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @namespace   Description: Declare and enter a new namespace. Only in C mode. Until -  an @endnamespace is found, all declarations will be regarded -  as living in this namespace. +  an @endnamespace is found, all declarations will be +  regarded as living in this namespace.   Arguments: <name>[::]    Where: -  <name> is a valid Pike identifier. Not the "absolute" name -  with dots. +  <name> is a valid Pike identifier. Not the "absolute" +  name with dots.   Children: Documentation for symbols in the namespace, or empty.   Groups with: -   Examples:    /*! @namespace lfun::    *! The operator callback API.    */    - ________________________________________________________________________________ - ================================================================================ + _______________________________________________________________________________ + ===============================================================================       DELIMITER KEYWORDS AT THE TOP LEVEL    - ================================================================================ + ===============================================================================      Keyword: @bugs - Description: Document shortcomings of the current block module/class/function + Description: Document shortcomings of the current block +  module/class/function   Arguments: -   Children: Text (with markup).   Groups with: -   Examples:    @bugs -  Converted images with bigger size than 512x512 pixels will be -  distorted in the corners. +  Converted images with bigger size than 512x512 pixels +  will be distorted in the corners.      XML: <bugs/> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @deprecated - Description: Documents the fact that the entity is deprecated by one or -  several other classes/modules/methods/variables. + Description: Documents the fact that the entity is deprecated by one +  or several other classes/modules/methods/variables.   Arguments: [item_1 [, item_2 [, item_3 ... ]]]    Where: -  [item_n] is an "absolute" name pointing to a Pike entity. It -  may use the 'scope::' prefix. +  [item_n] is an "absolute" name pointing to a Pike +  entity. It may use the 'scope::' prefix.   Children: -   Groups with: @deprecated   Examples:    //! @deprecated IO.initPrinter, IO.sendPrinterCommand    //! @deprecated predef::search      XML: `@deprecated Foo, Bar' =>    <deprecated>    <name>Foo</name>    <name>Bar</name>    </deprecated> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @example   Description: Example code for the documented item.   Arguments: -   Children: Text (with markup).   Groups with: -   Examples:    @example    array a = func();    if (sizeof(a) > MAX) // security check    exit(1);      XML: <example/> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @fixme   Description: Note about something that needs fixing in the manual.   Arguments: -   Children: Text (with markup).   Groups with: -   Examples:    @fixme -  The return values of this function is not correctly documented. -  +  The return values of this function is not correctly +  documented.   XML: <fixme/> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @note   Description: Important information about the documented item.   Arguments: -   Children: Text (with markup).   Groups with: -   Examples:    @note -  Do not call this function unless you know what you are doing. -  No bounds/sanity checking on arguments is performed! +  Do not call this function unless you know what you are +  doing. No bounds/sanity checking on arguments is +  performed!      XML: <note/> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @param   Description: Documentation for a method parameter. Only allowed when    documenting functions.   Arguments: <name>    Where:    <name> is a valid Pike parameter name.   Children: The documentation for the parameter.   Groups with: @param   Examples:    @param x    @param y    The coordinates of the thing.    @param name    The name of the thing.      XML: `@param Foo' =>    <param name="Foo"/> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @returns - Description: Documentation for the return value of a method. The type of the -  return value is deduced from the declaration. + Description: Documentation for the return value of a method. The type +  of the return value is deduced from the declaration.   Arguments: -   Children: The doc.   Groups with: -   Examples:    @returns -  The square root of the sum of the cubes of the inverse numbers. +  The square root of the sum of the cubes of the inverse +  numbers.      XML: <returns/> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @seealso - Description: Refer to other stuff that is related to the entity in question. + Description: Refer to other stuff that is related to the entity in +  question.   Arguments: -   Children: Text (with markup).   Groups with: -   Examples: //! @seealso    //! @[calc_checksum_w()] is used for wide strings.      XML: <seealso/> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @throws - Description: Describes the conditions for an exception to be thrown from the -  function. + Description: Describes the conditions for an exception to be thrown +  from the function.   Arguments: -   Children: Text (with markup).   Groups with: -   Examples: //! @throws    //! Throws an exception if the file could not be created.      XML: <throws/> - ________________________________________________________________________________ - ================================================================================ + _______________________________________________________________________________ + ===============================================================================       TEXT MARKUP KEYWORDS    - ================================================================================ + ===============================================================================      Keyword: @array - @endarray   Description: Documentation of the layout of an array.   Arguments: [name]   Children: @elem   Groups with: -   Examples: @array    @elem mixed 0..    All elements are of type mixed.    @endarray      XML: `@array Foo' =>    <array name="Foo"> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @b{ ... @}   Description: Bold.   Children: Text that will be rendered in bold.   Examples: You really look @b{bold@}! - You mean @b{bald@}, don't you?      XML: <b>...</b> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @code{ ... @}   Description: Encapsulates a code block.   Children: Text that will be rendered as program code.   Examples: @code{    int fac(int i) {    if(i<2) return i;    return i*fac(i-1);    }    @}      XML: <code>...</code> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @dl - @enddl   Description: Render a definition list.   Arguments: -   Children: @item   Groups with: -   Examples: @dl    @item Britta    My first teacher. She was very nice.    @item Boris    One of the best tennis players in the universe.    @enddl      XML: <dl> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @elem - Description: Documentation for an array element or a range of array elements. -  Only inside @array - @endarray. + Description: Documentation for an array element or a range of array +  elements. Only inside @array - @endarray.   Arguments: <type> <index range>    Where:    <type> is the Pike type of the element at the index.    <index range> is one of the following:    number (at index number only)    number.. (from number to end of array)    number1..number2 (from number1 to inclusive number2)    ..number (from beginning to inclusive number)    And number can be an integer literal or an identifier:    4711 -42 MAX
pike.git/refdoc/keywords.txt:374:    The rest of the elements are strings.    @elem array(string) MIN..MAX    The elements at these positions are themselves arrays.      XML: `@elem string 1..2' =>    <elem>    <type><string/></type>    <minindex>1</minindex>    <maxindex>2</maxindex>    </elem> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @i{ ... @}   Description: Italics.   Children: Text that will be rendered in italics. - Examples: You really look @i{italic@}! - You mean @i{Italian@}, don't you? + Examples: You really look @i{italic@}! - You mean @i{Italian@}, +  don't you?      XML: <i>...</i> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @image{ ... @}   Description: Insert the specified image.   Children: The filename of the image file.   Examples: @image{chart2.png@}      XML: <image>...</image> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @int - @endint - Description: Documentation of the different values an integer may have. + Description: Documentation of the different values an integer may +  have.   Arguments: [name]   Children: @value   Examples: @int    @value 0    Ignore all zonks.    @value 1    Transform zonks into flutter.    @value -1    Remove all zonks.    @value 5..10    Do something.    @value 17..    Do something else.    @endit    - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @item   Description: A definition term inside @dl   Arguments: <name>    Where:    <name> is any string that will be the name of the term.   Children: Text (with markup)   Groups with: @item   Examples:      XML: <item name="..."/> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @mapping - @endmapping   Description: Documentation of the layout of a mapping.   Arguments: [name]   Children: @member   Examples: @mapping    @member int "ip"    The IP# of the host.    @member string "address"    The name of the host.    @endmapping      XML: <mapping name="..."/> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @member   Description: Documentation for a member of a mapping.    Only inside @mapping - @endmapping.   Arguments: <type> <index_value>    Where:    <type> is the Pike type of the value stored at the index.    <index_value> is the index value. Can be a string or integer    literal, or an identifier.   Children: -   Groups with: -   Examples: @member string "name"    @member int "age"    These two entries in the mapping provide personal data.      XML: `@member float "foo"' =>    <member>    <type><float/></type>    <index>"foo"</index>    </member> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @multiset - @endmultiset   Description: Documentation of the layout of a multiset.   Arguments: [name]   Children: @index   Examples: @multiset    @index "cat"    It's raining cats.    @index "dog"    It's raining dogs    @endmultiset      XML: <multiset name="..."/> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @index   Description: Documentation for a index in a multiset.    Only inside @multiset - @endmultiset.   Arguments: <index_value>    Where: -  <index_value> is the index value. Can be a string or integer -  literal, or an identifier. +  <index_value> is the index value. Can be a string or +  integer literal, or an identifier.   Children: -   Groups with: -   Examples: @index "cat"    @index "dog" -  If present, these symbols signifies that it is raining animals. +  If present, these symbols signifies that it is raining +  animals.      XML: `@index "foo"' =>    <index>"foo"</index> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @ol - @endol   Description: Creates an ordered list.   Children: @item   Groups with: -   Examples: @ol    @item    Open the door    @item    Walk through    @item    Close the door    @endol      XML: <ol>...</ol> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @pre{ ... @}   Description: Preformatted text.   Children: Text that will be rendered as is, e.g. whitespaces kept.   Examples: @pre{    +----------+------+--------+    | startbit | data | endbit |    +----------+------+--------+    @}      XML: <pre>...</pre> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @ref{ ... @} - Description: A reference to a Pike entity. There is also a shortcut for this -  keyword, since it is expected to be so common: @[ ... ] + Description: A reference to a Pike entity. There is also a shortcut +  for this keyword, since it is expected to be so common: +  @[ ... ]   Children: Text that will be interpreted as a Pike name.   Groups with: - - Examples: My favourite class is @ref{Vanilla.Ice.Cream@}, it tastes much -  better than @[Nougat.Glass] or @[`+]. +     -  + Examples: My favourite class is @ref{Vanilla.Ice.Cream@}, it +  tastes much better than @[Nougat.Glass] or @[`+]. +    XML: <ref>...</ref> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @section - @endsection   Description: Begin a new section in the text.   Arguments: <name>    Where:    <name> is any text that is the name of the section.   Children: Text (with markup)   Groups with: -   Examples:    @section One - Introduction    ...    @endsection    @section Two - Intrinsics & Details about the Interface    ...    @endsection      XML: <section name=" ... "> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @string - @endstring   Description: Documentation of the layout of a mapping.   Arguments: [name]   Children: @value   Examples: @string    @value "GMT"    Greenwich Mean Time    @value "CET"    Central European Time    @endstring      XML: <string name=" ... "/> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @tt{ ... @}   Description: Teletype.   Children: Text that will be rendered in teletype.   Examples: Type @tt{rm -rf *@} to erase several days of work.      XML: <tt> ... </tt> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @ul - @endul   Description: Creates an unordered list.   Children: @item   Groups with: -   Examples: @ul    @item    2 oz light rum    @item    Juice of ½ lime    @item    Coca Cola    @endul      XML: <ul>...</ul> - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @url{ ... @}   Children: Text with markup.   Note: Might be deprecated, since it isn't used... - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @xml{ ... @} - Description: XML escape. Inside this tag the characters <>& are not quoted and -  this makes it possible to insert raw XML. Note that the usual -  rules apply to @ and that @i{...@}-style tags can be used inside. + Description: XML escape. Inside this tag the characters <>& are not +  quoted and this makes it possible to insert raw +  XML. Note that the usual rules apply to @ and that +  @i{...@}-style tags can be used inside.   Children: Text with markup.   Examples: @xml{<b>Bold</b> and @i{italic@}@}      XML: No representation. - ________________________________________________________________________________ + _______________________________________________________________________________      Keyword: @ignore - @endignore - Description: Ignores the block of code enclosed between the two keywords. Useful -  for code that the AutoDoc parser cannot understand. + Description: Ignores the block of code enclosed between the two +  keywords. Useful for code that the AutoDoc parser cannot +  understand.   Children: -   Examples: @ignore    array PROXY(_indices, ::_indices());    array PROXY(_values, ::_values());    @endignore - ________________________________________________________________________________ -  + _______________________________________________________________________________