From f775bd0f8cb5bbfd392f27fe3a531923f376febb Mon Sep 17 00:00:00 2001 From: Ryan Bloom Date: Sat, 29 Jul 2000 14:30:29 +0000 Subject: [PATCH] Add a small doc on how to document the APIs for use with ScanDoc. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@85933 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/developer/documenting | 43 +++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/manual/developer/documenting diff --git a/docs/manual/developer/documenting b/docs/manual/developer/documenting new file mode 100644 index 0000000000..0994b10d78 --- /dev/null +++ b/docs/manual/developer/documenting @@ -0,0 +1,43 @@ +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: + * 
+ *                 "/foo/bar/gum"   -> "gum"
+ *                 "/foo/bar/gum/"  -> ""
+ *                 "gum"            -> "gum"
+ *                 "wi\\n32\\stuff" -> "stuff"
+ *
+ * @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 + -- 2.40.0