• CodeDocumentation

K42 Code Documentation

We're using Doxygen to provide documentation of the K42 source. Doxygen creates its output from in-line comments in a specific format.

If you're working on the K42 tree (either adding functions or classes, or altering existing ones), it'd be a great help if you could document any classes/functions/structures/macros that you add, as well as any that you come across (especially if you've discovered something non-obvious about it).

There's a daily snapshot of the k42 tree documented at http://k42.ozlabs.org/doxygen/

Generating the Documentation

You'll need a local installation of the doxygen utility - most distributions provide a binary package. If not, the doxygen website is at http://doxygen.org.

All you need to do is run the doxygen command from the kitchsrc/doc/doxygen directory. This will create the output under ./html/.

Doxygen Comment Format

The full reference to doxygen comments is here, but I've include a quick reference below:

Here's an example from FRKernelPinned.H:

Documentation for the FRKernelPinned class itself:

/**
 * An interface to kernel pinned memory. Currently used for providing a
 * userspace process with a region in which it can place an object to be
 * loaded by the kernel.
 */
class FRKernelPinned : public FRCommon __xbase(FR) {

Comments starting with a  /**  are considered to be doxygen fragments, and are associated with the following class. If a class has no documentation, then it is inherited from the parent class.

Comments may contain special tags, which are useful for commenting arguments of functions. For example, the FRKernelPinned::_Create() function:

    /**
     * Create a region of kernel pinned memory, and return the virtual
     * address that the kernel will use to reference it.
     *
     * @param frOH the Object handle
     * @param kaddr the kernel's virtual address for this page
     * @param size the size of the region to allocate
     * @param callerPID the calling process' PID
     * @return 0 on success, -1 on failure
     */
    static SysStatus _Create(__out ObjectHandle &frOH,
        __out uval &kaddr,
        __in uval size,
        __CALLER_PID callerPID);

Not surprisingly, the  @param <parmeter> <description>  tag describes a specific parameter, and @return <description> describes the return value.

Many other tags are available (listed here), but some handy ones are:

• @todo - describes a todo element. All the todo items are grouped on a separate page of the output

• @warning and @note - adds a note or warning to the output

• @sa - (short for 'see also') provides a link to another class or function

Function documentation is also inherited if there is no explicit documentation available.