
Improved Doxygen documentation and search for C++ projects - mosra
https://blog.magnum.graphics/meta/improved-doxygen-documentation-and-search/
======
sharpercoder
I have installed doxygen on a handful of projects. In hindsight, it was a
waste of time. No one reads generated codedoc, yet everyone just read the
code.

Doxygen should be replaced with rendered comments in IDEs/code editors. That's
the real solution.

~~~
mosra
Exactly. Doxygen implicitly generates useless info about what file is included
by what file, list of places from where a function gets called, what line was
this and that function declaration in (and where is the definition), huge
class inheritance diagrams, entangled monstrous file dependency diagrams,
alphabetical file index, alphabetical symbol index, including every possible
undocumented symbol and file it can find and tons and tons of other stuff that
has a total value of 0.

The user should visit docs to get to know a high-level overview of a library
or human-readable explanation of an algorithm. Not to see stuff that's already
explained by the code itself.

So here I threw away all this noise and the theme is actively forcing the
library authors to focus on important stuff in the docs, explicitly excluding
useless things that could be auto-generated. "Installing Doxygen on a project"
achieves nothing, one has to write the actual docs first.

The result? See for yourself:
[https://doc.magnum.graphics/magnum/namespaceMagnum_1_1Animat...](https://doc.magnum.graphics/magnum/namespaceMagnum_1_1Animation_1_1Easing.html)

~~~
abathur
Doxygen can generate a lot of data most projects don't need (and may not have
the best defaults). Especially for external docs.

There's a lot of value in shaping/limiting options and choices to make Doxygen
easier to use for focused, high-quality external docs, but I'm not sure it
follows that the other information it can generate is useless.

~~~
mosra
For the record, nobody complained when I removed all the class diagrams and
other things mentioned above, so my takeaway was that ... yes, those features
were useless :) On the other hand, people complained about lack of essential
features that Doxygen didn't have, like proper search or #include information
for non-class members.

~~~
abathur
Sure. You're doing useful work shaping something that is a bit too free-form
for most. I didn't question your curation. Nor do I think your project needs
to support them.

But the fact that you haven't heard from the inevitably short list of projects
that have looked for new documentation tools in the past ~14 months and also
happen to be complex enough to benefit from niche features like inheritance
diagrams doesn't mean they don't exist.

------
steeve
Magnum truly has the most beautiful/polished doc I've ever seen.

Even more impressive considering it's a C++ project.

~~~
blattimwind
I never heard of it before but boy do these docs look and read well on a first
skim. Thoroughly impressed in just a few seconds.

------
vitaut
Sphinx ([http://www.sphinx-doc.org](http://www.sphinx-doc.org)) used by Python
and some C++ projects like LLVM provides a modern high-quality alternative to
Doxygen.

~~~
mosra
Not really an alternative, since C++ projects often use Breathe to "transpile"
Doxygen to Sphinx. I even contributed a few patches to Doxygen from which the
Breathe/Sphinx project directly benefited, but after trying it out a bit and
hitting a few walls, I realized I would achieve better flexibility by having
my own frontend.

Especially because (if I can dare to say) I ended up with a much better search
than what Sphinx (or Doxygen) has -- try it out:
[https://doc.magnum.graphics/magnum/?q=max#search](https://doc.magnum.graphics/magnum/?q=max#search)
;)

~~~
blattimwind
Yes, the search functionality in Sphinx leaves a lot to be desired, even if
you are already writing your own Sphinx plugin it is fairly difficult to add
stuff to the search indices in a meaningful way. It's also slow. Overall
Sphinx suffers a lot from hardcoding the reST data model and directly working
with that.

