pgsql-hackers
❮
Proposal: doxygen + MAN 7 pages
- Jump to comment-1Bear Giles<bgiles@coyotesong.com>Jan 29, 2026, 4:43 PM UTCThis started because I was looking for MAN pages for a number of functions.
They're documented on the website but there aren't MAN pages for them.
(Except SPI_*, and I don't think they're bundled in any of the
debian/ubuntu packages by default. However I would need to double check.)
Doxygen is a common approach for this - it only requires annotating code
comments that should already be there (cough) and can produce
Docbook/SGML in addition to manpages, HTML, Latex, etc.
But... libpq has a lot of functions, it is not clear what purpose many of
them serve, etc., so MAN 3 pages won't be enough.
Enter OpenSSL. If you look at its documentation it has a MAN 3 page for
each function, but more importantly it also has MAN 7 pages that provide
the context required to use a number of related functions. With libpq there
would be a 1-to-1 relationship between the official documentation and a MAN
7 page. (Mostly - there are some pages with a single deprecated function so
they don't need to be added.)
Each of these pages would refer to the official pages... and working sample
code.
I have a POC implementation and plan to create a PR for other people to
review later. I'm currently focused on getting some sample code to compile
but this is far enough along that a PR shouldn't take long to produce. I
wanted to give you a heads up since the man and related HTML pages should
definitely be included in libpq-dev.
......
On a similar note I saw the SPI_* pages - and the same thing applies.
Custom extensions using the API, not a PGXN wrapper, is not for the faint
hearted. But if someone is willing to take it on it would be a tremendous
help to have some MAN 7 pages that cover the required macros, palloc/pfree,
the fact that each connection/session runs in its own thread, etc.
Bear