[or-cvs] Add Doxygen config file and make target, along with section...

[nickm@seul.org (Nick Mathewson)]

Update of /home/or/cvsroot/doc
In directory moria.mit.edu:/tmp/cvs-serv26177/doc

Modified Files:
	HACKING 
Log Message:
Add Doxygen config file and make target, along with section in HACKING document

Index: HACKING
===================================================================
RCS file: /home/or/cvsroot/doc/HACKING,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- HACKING	30 Mar 2004 03:20:38 -0000	1.8
+++ HACKING	7 May 2004 17:03:52 -0000	1.9
@@ -414,6 +414,52 @@
   the message (perhaps with a string like "internal error").  Option (A) is
   to be preferred to option (B). -NM]
 
+2.5. Doxygen
+
+  We use the 'doxygen' utility to generate documentation from our source code.
+  Here's how to use it:
+
+  1. Begin every file that should be documented with
+         /**
+          * \file filename.c
+          * \brief Short desccription of the file
+          */
+
+     (Doxygen will recognize any comment beginning with /** as special.)
+
+  2. Before any function, structure, #define, or variable you want to
+     document, add a comment of the form:
+
+        /** Describe the function's actions in imperative sentences.
+         *
+         * Use blank lines for paragraph breaks
+         *   - and
+         *   - hyphens
+         *   - for
+         *   - lists.
+         *
+         * Write <b>argument_names</b> in boldface.
+         *
+         * \code
+         *     place_example_code();
+         *     between_code_and_endcode_commands();
+         * \endcode
+         */
+
+  3. Make sure to escape the characters "<", ">", "\", "%" and "#" as "\<",
+     "\>", "\\", "\%", and "\#".
+
+  4. To document structure members, you can use two forms:
+
+       struct foo {
+         /** You can put the comment before an element; */
+         int a;
+         int b, /**< Or use this form to put the comment after the element. */
+       };
+
+  5. See the Doxygen manual for more information; this summary just scratches
+     the surface.
+
 3. References
 
   About Tor