The ZFS code base is documented with Doxygen styled C comments.

To ensure consistency, please adhere to the following guidelines when writing ZFS code:

• General
  • Doxygen comments in ZFS use the Javadoc style.
  • For objects that support brief comments (files, functions, data structure fields), it is assumed that "auto-brief" is enabled and that the first sentence of the description will be rendered as a brief comment.
  • All comments should add information that cannot be easily descerned from the code directly. For example, don't add Doxygen comments to function paramters like boolean_t enable where the paramter's meaning is already well expressed by its type and/or name.
• Files
  • At the top of every .c and .h file should be a \file tag containing the filename.
  • Below that should be a a one-line "brief" description of the file's purpose.
  • Below that should be the detailed description of the file. It should be as thorough as possible and visual markup is encouraged where appropriate.
  • Additional sections of file scope information may occur elsewhere in the file (e.g. the description of an algorithm implemented by a group of functions that follows), but must be tagged with \file so that it is properly aggregated by Doxygen.
• Functions
  • API documentation should be located immediately above the function declaration in the header exposing this API.
  • The API documentation for static/module local functions should be located immediately above the function definition (not declaration).
  • Implementation documentation should be located immediately above the function's definition (not declaration).
  • Every function's documentation may contain:
    • A "brief" one-line description.
    • A \param tag for every parameter warranting additional documentation. Where it is not already clear from C context, the parameter's direction should be specified. The direction can be either [in] for an input to the function, [out] for an output, or [in,out] for a bidirectional parameter.
    • A description of the return value. This may be done using either a single \return tag, or multiple \retval tags. \retval tags are prefered where the return value has a few discrete possibilities.
    • Any \invariants, if applicable.
    • A detailed description including information pertinent to those modifying the function.
    • Any important \notes or \todo>s, if applicable.
• Data structures
  • Structs should be documented at their definitions. The documentation block should contain a "brief" one-line description, and a detailed description (if necessary).
  • Members' documentation can be either above the member or in-lined using a "<" comment just after the member.
• Tunables
  • ZFS contains multiple tunable knobs that can be set at module/kernel load time or during operation. They should be documented by placing their definitions in a \addtogroup tunables block, or including an \ingroup tunables directive in their documentation block.

    Todo:

    Devise an elegant method for including the tunable's path in the documentation. For example, the documentation for zfs_no_write_throttle should tell you that its path is "vfs.zfs.no_write_throttle".

Here is an example of the above guidelines:

/**
 * \file example.c
 * Examples on proper doxygen usage.
 *
 * This file contains examples of how to properly use doxygen markup in the 
 * ZFS module.  Also, it can help you concatenate strings
 */

/**
 * Classroom Roster Element
 *
 * The classroom roster is a single linked list that stores all students'
 * information.  This struct is one element in the list
*/
struct roster_elem {
	/**
	 * A key to the student's last report card in the database.  
	 *
	 * \note  The database is volatile; the key will be invalid following a
	 *        reboot.  Do not save the key to persistent storage.
	 */
	int report_card_key;
	char name[80];	/**< The student's name */
	bool is_male;	/**< True iff the student is a boy */

	/**
	 * pointer to next elem in list.  
	 * A null value signifies end of list
	 */
	struct roster_elem* next;
};

/**
 * Concatenate two strings
 *
 * Copies the C-string pointed to by src to the end of the C-string pointed
 * to by dest.
 *
 * \warning  Does not verify that dest has enough space available.  This can 
 * 	     lead to buffer overflows.  It is recomended to use strncat or
 * 	     strlcat instead.
 *
 * \param[in,out] 	dest	Pointer to the destination string
 * \param[in]		src 	Pointer to the source string
 *
 * \return  A pointer to the resulting string dest
 */
char *
strcat(char *dest, const char *src)
{
  return (0);
}