I wrote a small C library for Linux and FreeBSD, and I'm going to write the documentation for it. I tried to learn more about creating man pages and not found the instructions or descriptions of best practices making man pages for libraries. In particular I'm interested in what section to put man pages of the functions? 3? Maybe there good examples or manuals? Create man pages for each function from the library a bad idea?
Manual pages for a library would go in section 3.
For good examples of manual pages, bear in mind that some are written using specific details of groff and/or use specific macros which are not really portable.
There are always some pitfalls in portability of man-pages, since some systems may (or may not) use special features. For instance, in documenting
dialog, I have had to keep in mind (and work around) differences in various systems for displaying examples (which are not justified).
Start by reading the relevant sections of
man man where it mentions the standard macros, and compare those descriptions for FreeBSD and Linux.
Whether you choose to write one manual page for the library, or separate manual pages for the functions (or groups of functions) depends on how complicated the descriptions of the functions would be:
- ncurses has a few hundred functions across several dozen manual pages.
- dialog has several dozen functions in one manual page. Others will be sure to show many more examples.
I've been documenting my scripts with it by using
END_MAN delimited heredocs and my C/C++ code by using the same
END_MAN delimited heredocs
/* */. Either is easily extractible with sed and then renderable into a manpage. (With a little bit of UNIX signal hackery along with inotifywait, you can extract and view your manpage sections live and have the manpage browser reload as the source updates. )
As for the section, then 3 would be it for a user-level C library. You can read about the section numbers (among other things) in man(1).
If you want to see some readable, well-structured example man pages, I'd take a look at
the Plan9 https://swtch.com/plan9port/unix/ libraries where you can see how the very creators of
UNIX and its documentation system probably intended for these things to work.
This markdown language has been adopted by python for its documentation, and is much easier to learn, write and maintain, than the good old troff man macros which rst2man will generate for you from your reStructuredText.
You could document the API using doxygen to provide the reference as HTML, and also generate man pages and other formats for offline reading.
The advantage of doxygen is that it's sort of "inline" documentation like JavaDoc or PythonDoc, doubling as interface comments (or vv., comments doubling as doc text); you add the doc texts to your source/header files, and it's extracted from there, which improves the chances of being held up to date.