[Giovanni]

about

Pawn offers a great feature for documentating scripts. This feature is called 'Documentation Comments'.
The compiler translates them at compile time and makes simple XML files out of them. These files are really helpful for people who are writing libraries/APIs.
This comments look nearly like normal comments, however there is a slight difference:

Код:

Singleline documentation comment: /// <Documentation here>
Multiline documentation comment: /** <Documentation here> */

Notice that the singleline comment starts with 3 slashes and that the multiline comment starts with 2 stars (but ends with 1 star). This is really important since the compiler would otherwise simply ignore them.



xml tags

You are not supposed to simply write the text after the documentation comments like you are used from normal ones. There are specific XML tags which the compiler knows. Here is a list of them:

Tag	Usage
<summary>{TEXT}</summary>	The discription of a function.
<param name="{NAME}">{TEXT}</param>	The discription of a parameter from a function.
<returns>{TEXT}</returns>	The discription of the value/variable which this function returns.
<remarks>{TEXT}</remarks>	A little note related to the function.

generating the documentation file


Simply compiling scripts with documentation comments in Pawno (with default settings) will not work. Therefore I am simply going to compile my script over the command prompt. Following command will compile your script and generate the documentation file (.xml):

Код:

pawncc -r {FILENAME}.pwn

example

My example code looks like following:

pawn Код:

/**
    <summary>
        This is a simple add function.
    </summary>

    <param name="a">
        The first parameter of the addition.
    </param>

    <param name="b">
        The second parameter of the addition.
    </param>

    <returns>
        The sum of the addition.
    </returns>

    <remarks>
        This function is really simple. You actually do not need an include for it.
    </remarks>
*/
forward add(a,b);

public add(a, b)
{
    return (a+b);
}

The file is called 'test.pwn', therefore I am going to use following command to compile it:

Код:

pawncc -r test.pwn

The output is the usual .amx file AND a .xml file. If you opened this file in your browser it would not look very good. The reason for that is quite simple. The documentation file requires a stylesheet. This stylesheet is called pawndoc.xls (>DOWNLOAD<).

If your .xml file shall be in the same folder as this stylesheet, you must open the .xml file and edit the 2nd line. It should look like this:

Код HTML:

<?xml-stylesheet href="pawndoc.xsl" type="text/xsl"?>

If you open the .xml file in your browser now, it will look like following: