wiki:doc/CodingForTor/LoggingAndDocumentation

Log conventions ~

https://wiki.torproject.org/noreply/TheOnionRouter/TorFAQ#LogLevels

No error or warning messages should be expected during normal OR or OP operation.

If a library function is currently called such that failure always means ERR, then the library function should log WARN and let the caller log ERR.

[XXX Proposed convention: every message of severity INFO or higher should either (A) be intelligible to end-users who don't know the Tor source; or (B) somehow inform the end-users that they aren't expected to understand the message (perhaps with a string like "internal error"). Option (A) is to be preferred to option (B). -NM]

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 description of the file.

/

(Doxygen will recognize any comment beginning with / as special.)

  1. 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

*/

  1. Make sure to escape the characters "<", ">", "\", "%" and "#" as "\<",

"\>", "
", "\%", and "\#".

  1. 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 the less-than symbol to put the comment

  • after the element. */

};

  1. To generate documentation from the Tor source code, type:

$ doxygen -g

To generate a file called 'Doxyfile'. Edit that file and run 'doxygen' to generate the API documentation.

  1. See the Doxygen manual for more information; this summary just

scratches the surface.

Doxygen comment conventions

Say what functions do as a series of one or more imperative sentences, as though you were telling somebody how to be the function. In other words, DO NOT say:

/ The strtol function parses a number. *

  • nptr -- the string to parse. It can include whitespace.
  • endptr -- a string pointer to hold the first thing that is not part
  • of the number, if present.
  • base -- the numeric base.
  • returns: the resulting number.

*/ long strtol(const char *nptr, char nptr, int base);

Instead, please DO say:

/ Parse a number in radix <b>base</b> from the string <b>nptr</b>,

  • and return the result. Skip all leading whitespace. If
  • <b>endptr</b> is not NULL, set *<b>endptr</b> to the first character
  • after the number parsed.

/ long strtol(const char *nptr, char nptr, int base);

Doxygen comments are the contract in our abstraction-by-contract world: if the functions that call your function rely on it doing something, then your function should mention that it does that something in the documentation. If you rely on a function doing something beyond what is in its documentation, then you should watch out, or it might do something else later.

Last modified 6 years ago Last modified on Jun 11, 2011, 3:28:56 PM