Re: Library manpages per-function or per-library?

[Ingo Schwarze <schwarze@usta.de>]

Hi, Kristaps and Joerg,

Joerg Sonnenberger wrote on Wed, Nov 12, 2014 at 03:51:27PM +0100:
> On Wed, Nov 12, 2014 at 03:28:30PM +0100, Kristaps Dzonsons wrote:

>> I thought I'd put this question up for future searches, as it
>> confuses me and no doubt confuses others, as well.  In short, when
>> writing a library, does one document each function in a separate
>> mdoc(7) page, or all functions in one big one?  Or perhaps, grouped
>> by utility?  Or grouped by header file?

The usual policy in OpenBSD is one page per function, except when
that would cause substantial text duplication, in which case
functions get grouped into pages to avoid duplication.
Grouping a few closely related functions for other reasons
is also widely considered acceptable, in particular if the
amount of information per function is low, as long as the
number of functions per page doesn't grow too much.

> One man page documenting the general API design and one man page
> per function group.

That sounds like a sound policy, too, even though OpenBSD usually
skips the page documenting the general API design, explaining that
in whichever of the individual pages fits best.

Note that there are many cases where these policies are not
followed for various, often historical reasons, and that the
policies are not intended to be followed by the letter.
If, in a particular case, doing it a bit differently makes
the pages easier to use, that's OK.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv