Elaborate Function

Let's also study a function form of the elaborate command example. Again, I'll use C as my example. Since this is a bit more involved, you may feel a little lost if you're not familiar with C programming. I'll keep the technical jargon to a minimum.

Let's re-write hi as hello, accepting a Boolean (zero or one) integer of whether to capitalise, and an optional character string (a word) prefix. Let's also stipulate an integer return value.

If you're not familiar with C, the const char * and int parts are part of the C language. Note that the C and prefix names haven't changed.

The include file (In) and function return type (Ft) are unchanged but for the type (int instead of void). I've added an explicit-scope macro pair Fo and Fc, syntactically like Bl and El, that encloses the function's arguments.

This renders as follows. Note that the formatter is smart enough to comma-separate the Fa macros.

It's clear that the Fo macro accepts the function name (as Fn did for the simple example), but it also opens a function prototype scope. This scope is closed by Fc. The contained Fa macros are for function arguments.

If you're wondering why I didn't use Fn as in the last section, it's a matter of readability. Using Fn puts everything on one long line, such as the following.

This works with two arguments, but can quickly run into long lines. In general, your mdoc manual shouldn't exceed 78 characters per line. Shorter lines are useful when managing manuals in cvs or other version management systems — we'll discuss this in later sections of this book.

The quoted arguments to Fa may seem superfluous, but each argument to the Fa, for the C language, refers to a type and variable name. Since one may specify several arguments to a single Fa, the quotes are necessary for signifying a single argument type and name.

This renders as follows, with the Fa scope highlighted.

In the C language, function prototypes don't necessarily need named function arguments. However, it's good practise to name arguments when documenting them in the SYNOPSIS so that we can consistently refer to them later on in the manual. Let's refer to them now in the DESCRIPTION, where we document our arguments.

Note that there are no set conventions for documenting function arguments in the DESCRIPTION body. Sometimes this is done within the flow of a regular sentence. Other times, as below, we'll introduce each argument as part of a list.

Here, we see the familiar Bl and El list enclosure. Notice how I re-use the Fa macro to document individual arguments, just like I re-used Fl and Ar when documenting command-line flags and arguments. In the last section, I mentioned why we use Fn instead of Nm for re-stating the name.

This renders as follows.

Finally, let's add a section documenting the return value of this function. This will differ from the simple example in that we actually return a value.

Piecing this example together, we have the following the following respectable C function manual.

Running through our checklist, we see that we've described preprocessor information with the header file macro In; function calling syntax and types in the SYNOPSIS; and arguments in the DESCRIPTION along with function operation. This contains all we need to know about the function.

Last edited by $Author: kristaps $ on $Date: 2014/04/07 21:27:38 $. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.