Simple Function

Let's study a simple C function, hi, which prints hello, world just like in prior sections. We begin with the familiar first macros.

All that's changed is the manual category, from 1 to 3. We'll discuss manual categories later in this book. Suffice to say that programming functions and libraries (not system calls!) are in category 3.

The calling syntax of our function is documented in the SYNOPSIS section. Assume that our function prototype is within the header file hi.h as void hi(void), which, in non-programming terms, declares that a function hi accepts no arguments and does not return a value.

This introduces three unfamiliar macros. The In macro specifies an include file that interfacing programmes will need to include. The Ft and Fn macros collectively document the function (return) type and function name. Since not all languages have return types, the Ft macro is optional in this context.

By now it comes as no surprise that Ft is scoped to the end of its line, as is Fn in this example. In fact, both of these macros are syntactically similar to the Ar and Fl found in the first chapter: their scopes are closed by subsequent macros on the same line.

Since our function has no arguments or return values, all we need to do is add some bits in the DESCRIPTION section to complete this manual.

Here, you'll notice a difference between a function and command manual. It's clear that we refer back to our invoked command using Fn instead of Nm. Why is this? The Nm macro, when used in the body of a manual, refers to the command name, not the manual name, as we used Nm to annotate that utility name in the SYNOPSIS. In functions, we use the Fn macro. The difference is that Fn won't repeat the manual name if used without arguments. This complexity is simply the result of poor planning in the mdoc language.

Let's visualise the output so far:

Lastly, let's stipulate the function return value in its own section, RETURN VALUES. This mirrors the EXIT STATUS introduced for hello.1. Although we don't have a return value, it's good practise to include this section anyway.

Although this example is instructive, it's quite simple. Let's review our checklist before moving on.

Did I describe the preprocessing and linking information?

Yes, a header file. There is no linking information.

Did I describe the calling syntax of each function and variable?

Yes, the hi function.

Did I describe the type of each function and variable?

Yes, as hi has neither type nor value.

Did I describe each argument in each calling syntax?

This does not apply, as it has none.

Did I describe each function's operation?

Yes, in that it prints hello, world.

Did I describe each function's side effects?

This does not apply, as it has none.

Very few real-world functions are so simple. In the next section, we introduce a more practical function with types and arguments.

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