diff --git a/.autodoc_inlining b/.autodoc_inlining
index a593ba86282829e6bbd355a9a3ea220ae7b42043..a4f99eb5fde6799e7420a508b6dbd56652bcf00e 100644
--- a/.autodoc_inlining
+++ b/.autodoc_inlining
@@ -82,8 +82,8 @@ b) Pike files
Doc comments look like:
- //. yadda yadda yadda
- //. yadda yadda
+ //! yadda yadda yadda
+ //! yadda yadda
To be considered one doc block, the comments must be separated only by
whitespace and _one_ "\n", that is they have to be on adjacent lines
@@ -93,7 +93,7 @@ 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:
- //. Doc for alpha
+ //! Doc for alpha
int alpha()
{
return 4711;
@@ -101,24 +101,25 @@ the code, without intervening blank lines. Examples:
static int undocumented;
- //. Error! This doc block has no destination!
+ //! Error! This doc block has no destination!
int beta;
- //. Doc for beta
+ //! Doc for beta
- //. Doc for gamma, delta, and epsilon
+ //! Doc for gamma, delta, and epsilon
int gamma, delta;
float epsilon;
- //. Error here!
+ //! Error here!
int zeta;
- //. ambiguous which doc to associate with zeta.
+ //! ambiguous which doc to associate with zeta.
int eta;
- //. Error here too! ambiguous which variable is documented.
+ //! Error here too! ambiguous which variable is documented.
int theta;
- //. Doc for two methods. This is so UGLY!
+ //! Doc for two methods. This is so UGLY! We strongly recommend
+ //! using the decl keywords instead to accomplish this effect.
int methodOne()
{
...
@@ -128,7 +129,7 @@ the code, without intervening blank lines. Examples:
...
}
- //. However, it can be useful sometimes, for short methods:
+ //! However, it can be useful sometimes, for really short methods:
int very_short() { return 4711; }
int even_shorter() { return 0; }
@@ -136,13 +137,13 @@ the code, without intervening blank lines. Examples:
In Pike files, you can not use @class or @module to tell which module
or class you are in. To document a class, you simply write:
-//. Doc for the class
+//! Doc for the class
class CheeseMaker
{
- //. You can even document inherits!
+ //! You can even document inherits!
inherit Earth : earth;
- //. Doc for CheeseMaker->a()
+ //! Doc for CheeseMaker->a()
int a()
{
...
@@ -159,8 +160,8 @@ documentation comments but is itself undocumented:
class a()
{
- //. @decl foo
- //. ... doc for foo ...
+ //! @decl foo
+ //! ... doc for foo ...
}
If a doc block is the first in a file, and it has no target, then it
@@ -171,13 +172,13 @@ keyword. If a doc comment begins with some @decl keywords, these
@decl's act just like real declarations standing next to the doc.
Thus:
- //.@decl int a(int x)
- //.@decl int b(int x)
- //. Here is some doc for these functions....
+ //! @decl int a(int x)
+ //! @decl int b(int x)
+ //! Here is some doc for these functions....
is autodocwise equivalent to:
- //. Here is some doc for these functions....
+ //! Here is some doc for these functions....
int a(int x)
{
.....
@@ -193,11 +194,11 @@ the @decl keyword at the block beginning. That is when you document
and all @decl's must be methods that have the same name as the real
method:
- //.@decl float cube(float x)
- //.@decl int cube(int x)
- //. Gives x**3.
- //.@param x
- //. The number to cube.
+ //! @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)
{
....
diff --git a/.autodoc_syntax b/.autodoc_syntax
index 741bcdaff704f069da0d86c3d01d897531aabcac..814c325b9c99bcd4c1f4ffd056a140319c9f87df 100644
--- a/.autodoc_syntax
+++ b/.autodoc_syntax
@@ -11,12 +11,12 @@ long, it can be broken into several lines. A trailing @ on the line
indicates that it continues on the next line. The @ and the newline
character will be discarded, and the lines merged. Thus:
- //. @variable thisVariableNameIsSoLong@
- //.YouJustCantBelieveIt
+ //! @variable thisVariableNameIsSoLong@
+ //!YouJustCantBelieveIt
will appear to the parser as:
- //. @variable thisVariableNameIsSoLongYouJustCantBelieveIt
+ //! @variable thisVariableNameIsSoLongYouJustCantBelieveIt
This is sometimes necessary because keywords that take parameters
expect all the parameters to appear on the same line and treat the end
@@ -29,10 +29,10 @@ 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:
- //. - I love you, said Danny.
- //.
- //. - You have no right to come here after what you did to
- //. my little dog, screamed Penny in despair.
+ //! - I love you, said Danny.
+ //!
+ //! - You have no right to come here after what you did to
+ //! my little dog, screamed Penny in despair.
will generate the following XML:
@@ -87,7 +87,7 @@ alone (with their parameters, if any) on one line.
@ must still be quoted with @@. < and > must also be quoted unless
the intention really is to write XML. For example:
- //. He is so @xml{<i>italic</i> and @b{bold@}!@}!!
+ //! He is so @xml{<i>italic</i> and @b{bold@}!@}!!
will generate the following XML:
@@ -103,20 +103,20 @@ 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:
- //. @decl int dist(int x, int y)
- //. Calculates the distance.
- //. @param x
- //. @param y
- //. The coordinates of the vector.
+ //! @decl int dist(int x, int y)
+ //! Calculates the distance.
+ //! @param x
+ //! @param y
+ //! The coordinates of the vector.
Above, the two @param'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:
- //. Error, can't group @note and @param:
- //. @param x
- //. @note
- //. Don't use this function. At all. Ever.
+ //! Error, can't group @note and @param:
+ //! @param x
+ //! @note
+ //! Don't use this function. At all. Ever.
======================================================================
@@ -142,28 +142,28 @@ keyword:
quoting character itself is in the string, a duplication is used to
quote it:
- //. @question "He is a ""swapper""?!"
+ //! @question "He is a ""swapper""?!"
However, if your parameter contains only one of ' and ", then it is
smarter to choose the other one as the quouting character:
- //. @question 'He is a "swapper"?!'
+ //! @question 'He is a "swapper"?!'
It is an error not to end a quote before the end of the line:
- //. @wrong "Aww, come on now, this worked fine in C64 basic!
+ //! @wrong "Aww, come on now, this worked fine in C64 basic!
If a quoted parameter is too long to fit in one line, use the @ at
the end of the line to merge it with the following:
- //. @right "Oh, joy! Now I can make my parameters just as@
- //. long as I want them!"
+ //! @right "Oh, joy! Now I can make my parameters just as@
+ //! long as I want them!"
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:
- //. @look "\n"
+ //! @look "\n"
The parameter will be a string with two characters, a backslash
followed by the letter n.