How can I publish package overviews (Java) or namespace overviews (C++) using Doxygen?
We use doxygen to generate API (reference) documentation for our code. We have a small Java API and a large C++ API. The usual tool of choice for Java APIs is Javadoc, but doxygen can do both and we have decided to use a single tool for both.
With Javadoc you can add an overview for any package by adding a specially-named file to the source code. Javadoc then shows this overview, with as much documentation as you care to include, along with the documentation for the individual classes. Package overviews are useful for explaining how groups of related classes are intended to be used together, and can include diagrams, examples, and more. Because they're part of the Javadoc build, they can link to individual classes (or methods or other members).
How do I do the equivalent in doxygen, for both Java packages and C++ namespaces (which we use kind of like packages)? I know I can edit the main page, which functions as an overview of the entire API, but I want to distribute the documentation more. I don't want one overview page; I want one overview page per logical code partition, and I want that overview to be in the same directory as the code (where it'll be more likely to be kept up to date).
Is there a way to do this with doxygen, or am I going to have to write my own tools to add files to the doxygen output?
1 answer
We solved this by adding overview files in Markdown format into the source tree and making one small configuration change.
In Doxyfile, we set GENERATE_TREEVIEW to yes. This enables the sidebar table of contents, which is needed if you want these overview files to actually show up somewhere. (Normally doxygen just emits code elements -- classes, interfaces, and so on. The treeview gives you a place to put other things.) While you're editing Doxyfile, make sure MARKDOWN_SUPPORT is set to yes. (I think that's the default.)
We then added one Markdown file (.md extension) to each subdirectory in our source tree. Doxygen supports all the usual Markdown features. We named each file to match its containing directory. For example, in the "server" directory we named the file server.md.
The usual doxygen treeview has sections for namespaces, classes, files, and perhaps other things. (This might vary by language; ours is C++.) Our additional files show up in a section above these sections, which makes sense -- "classes" is only about the classes, and the package overview that explains how they work together sits above that. We didn't attempt fancier organization, as we needed only a few files at that level.
0 comment threads
0 comment threads