30.09.2012, 19:41
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:
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:
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):
example
My example code looks like following:
The file is called 'test.pwn', therefore I am going to use following command to compile it:
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:
If you open the .xml file in your browser now, it will look like following:
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> */
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
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);
}
Код:
pawncc -r test.pwn
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"?>
its a secet of samp ... 
