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. JHS is working on a more elaborate manual and style guide, which + will most likely appear in pike/autodoc/tags.txt when this file is discarded.    -  + ================================================================================ +  +  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. + 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: +  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. + 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. + 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. + Arguments: <name> +  Where: +  <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: +  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) + 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. + 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. + 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. + Children: - + Groups with: - + Examples: +  /*! @endmodule Roine */ +  + ________________________________________________________________________________ +  + 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. + Arguments: <name> +  Where: +  <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. */ +  + ________________________________________________________________________________ + ================================================================================ +  +  DELIMITER KEYWORDS AT THE TOP LEVEL +  + ================================================================================ +  + Keyword: @deprecated + 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. + 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: @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! +  + 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. + Arguments: - + Children: The doc. + Groups with: - + Examples: +  @returns +  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. + Arguments: - + Children: Text (with markup). + Groups with: - + Examples: //! @seealso +  //! @[calc_checksum_w()] is used for wide strings. +  + XML: <seealso/> + ________________________________________________________________________________ + ================================================================================ +  +  TEXT MARKUP KEYWORDS +  + ================================================================================ +  + Keyword: @array - @endarray + Description: Documentation of the layout of an array. + Arguments: - + Children: @elem + Groups with: - + Examples: @array +  @elem mixed 0.. +  All elements are of type mixed. +  @endarray +  + XML: `@array Foo' => +  <array name="Foo"> + ________________________________________________________________________________ +  + 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. + 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 + Children: Documentation for the array elements at the given index or +  indices. + Groups with: @elem + Examples: @elem int 0 +  The first element is an integer. +  @elem string 1.. +  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? +  + XML: <i>...</i> + ________________________________________________________________________________ +  + 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: - + 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: @ref{ ... @} + 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 @[`+]. +  + 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: @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: @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. + Children: Text with markup. + Examples: @xml{<b>Bold</b> and @i{italic@}@} +  + XML: No representation. + ________________________________________________________________________________ +    Newline at end of file added.