mirror of
https://github.com/apache/httpd.git
synced 2025-10-31 19:10:37 +03:00
f775bd0f8c
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@85933 13f79535-47bb-0310-9956-ffa450edef68
44 lines
1.3 KiB
Plaintext
44 lines
1.3 KiB
Plaintext
Apache 2.0 is using ScanDoc to document the API's and global variables in
|
|
the code. This will explain the basics of how to document using Scandoc.
|
|
|
|
To start a scandoc block, use /**
|
|
To end a scandoc block, use */
|
|
|
|
In the middle of the block, there are multiple tags we can use:
|
|
|
|
Description of this functions purpose
|
|
@param parameter_name description
|
|
@tip Any information the programmer should know
|
|
@deffunc function prototype.
|
|
|
|
The deffunc is not always necessary. ScanDoc does not have a full parser in
|
|
it, so any prototype that use a macro in the return type declaration is too
|
|
complex for scandoc. Those functions require a deffunc.
|
|
|
|
An example:
|
|
|
|
/**
|
|
* return the final element of the pathname
|
|
* @param pathname The path to get the final element of
|
|
* @return the final element of the path
|
|
* @tip Examples:
|
|
* <PRE>
|
|
* "/foo/bar/gum" -> "gum"
|
|
* "/foo/bar/gum/" -> ""
|
|
* "gum" -> "gum"
|
|
* "wi\\n32\\stuff" -> "stuff"
|
|
* </PRE>
|
|
* @deffunc const char * ap_filename_of_pathname(const char *pathname)
|
|
*/
|
|
|
|
At the top of the header file, we always include
|
|
|
|
/**
|
|
* @package Name of library header
|
|
*/
|
|
|
|
ScanDoc uses a new html file for each package. The html files are named:
|
|
|
|
Name of library header.html, so try to be concise with your names
|
|
|