pike.git
/
refdoc
/
keywords.txt
version
»
Context lines:
10
20
40
80
file
none
3
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.