11

I started out looking for a way to generate man pages from source code. I now have Doxygen setup, and it generates awesome HTML pages which are organized, helpful, etc.

But... it seems Doxygen sucks at creating decent or usable man pages. From more Google searches, it seems that may be the general consensus when it comes to using Doxygen to generate man pages. Is this really the case, or is there a page/hints which explains how to get Doxygen to do a better job with man pages?

I found one project -- doxy2man on GitHub -- which seems designed specifically to re-massage the Doxygen xml output files into man pages, but I'm curious to know if Doxygen itself can be coerced to do better.

The Doxygen options I'm using (there aren't many) for man pages are:

$ grep MAN Doxyfile | grep -v "#"
GENERATE_MAN           = YES
MAN_OUTPUT             = man
MAN_EXTENSION          = .3
MAN_LINKS              = YES
Jens
  • 69,818
  • 15
  • 125
  • 179
Stéphane
  • 19,459
  • 24
  • 95
  • 136
  • Just a side note: don't put the manpage in the source file; put it in the include file. The include has everything needed to use the code: class definitions, function prototypes, enum's, `#define`'s. It tells what the code does. (The source file tells how it works.) As such, the documentation for the code should be in the same file as the interface. It is the place where programmers go to figure out how to use the code. – shawnhcorey Jun 22 '18 at 12:05
  • You're using a hammer to drive a screw. Into glass. Really, the expressiveness of troff and doxygen differ widely. And source code comments are typically quite unrelated to man page contents. Don't bother and keep both separate and in separate files with formats invented to do one thing right. Doxygen for long enough has tried to be all things to all people and the result is far from charming. – Jens Dec 19 '20 at 20:03

0 Answers0