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

diff --git a/docs/manual/developer/documenting b/docs/manual/developer/documenting
new file mode 100644 (file)
index 0000000..0994b10
--- /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:
+ * <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
+