style/synopsis_func —
the SYNOPSIS section for library functions
Never use the
Lb macro unless the operating
system you are writing for strictly requires it; in that case, adhere to the
conventions of that operating system, but be aware that usage of
Lb is mostly unportable, and the result
will likely be unsatisfactory when reading the page on a different system.
This macro is not sustainable. It causes inflationary growth of the file
lib.in. All the same, that file will never
be complete, so
Lb will remain a
portability nightmare. For that reason, some systems, for example
OpenBSD, have decided to remove support for
Lb.
Precede each function prototype with the full set of headers that need to be
included to use the function, using
In
macros. Never use
Fd macros to show
#include directives. If several functions documented in the same manual page
require inclusion of the same set of headers, group these functions together
and do not repeat the set of headers. Whenever the next function uses a
different set of headers than the previous one, provide the full set of
headers required for the next function, even if some of the headers are also
required for the previous one.
Always provide the return type of each function with an
Ft macro, even if it is
void, then start the next input line with an
Fo or
Fn
macro.
For each argument of each prototype, provide both the type of the argument and a
name for the argument. If a function does not take any arguments, explicitly
specify
void as the second argument to
Fn.
To show the prototype of a function, using
Fo
usually results in more readable source code than using
Fn, in particular for functions having more
than one argument. Avoid input lines of 80 characters and more, and avoid
input line continuation with a backslash character at the end of an input
line.
For functions having only one single argument,
Fn is usually acceptable if the whole macro
fits on one input line, but there is nothing wrong with using
Fo for consistency with other, more
complicated functions on the same page. If the type and name are both very
short, using
Fn with two arguments may
result in source code that is easier to read.
Usually, manual authors do not need to consider vertical spacing in the SYNOPSIS
section; line breaks and blank lines automatically appear at useful places. If
a manual page documents a larger number of functions, these functions form two
or more logical groups, and two or more of the groups require the same header
files to be included such that no
In macros
are required in between, it may occasionally be useful to insert a paragraph
(
Pp) macro between two such groups to
separate the groups by a small amount of vertical whitespace.
.In math.h
.Ft double
.Fo atan2
.Fa "double y"
.Fa "double x"
.Fc
.Ft double
.Fn sin "double x"
.In unistd.h
.Ft void
.Fn sync void
The MACRO REFERENCE section in the
mdoc(7)
manual.