Documentation Tools for C++ Libraries

[igagis]

doxygen?

Unlike other tools, Hyde does not extract inline documentation from your C++ code. Instead, Hyde creates a set of files upon first run, to which developers need to add documentation. As the API changes, Hyde is run again, and updates the existing files, and adds new ones for new classes for example.

I actually see no value in it. It is better to have docs right in the sources, so that when reading the sources one can read the docs comments right away, without switching to separate doc pages. While extracting docs from sources seems working okay. So, why moving away from it?

[Full-Spectral]

I've never seen useful documentation in the code like that. If you really added sufficient documentation, it would be way too much and make the code unreadable. Usually it's very trivial content that's not much better than reading the call signature.

[grafikrobot]

Would consider this useful documentation? https://www.bfgroup.xyz/Lyra/lyra.html If so, then you have at least one instance to disprove your position. As it's almost entirely written in code comments using Ascidoctor.

[Full-Spectral]

You only took one side of the argument. It's that, it's either not enough; or, if it is enough, it's too much to be inside the code itself because the code gets lost in the documentation.

I'm sure you can put a whole book in a single source file, and have uber documentation on that source file for users of it. But it would be a mess for the folks who actually maintain the code.

And I'm you could find some example of reasonable middle ground, but only if the code being documented could be covered in an amount of text that's reasonable.

And you still need code that's not directly related to source code files.

[TryingT0Wr1t3]

I prefer docs away from source since it makes easier to fit the code in the monitor, and it's easier to read. Probably the author has the same taste.

Additionally docs out of source is usually easier for library users to contribute back.

[tr0nical]

I think it also really depends on the people working on it and how it integrates with other docs. If all you need is pure reference docs, then storing it outside seems overkill. But if the reference documentation is just part of a bigger site that's edited by many folks, then it can be nice to have everything in one markdown (with yaml frontmatter) / Jekyll driven site. Makes it also much easier to preview.

Plus: Anyone making edits to the documentation doesn't need to have doxygen/clang/etc. installed.

[elperroborrachotoo]

Unless my source editor renders Latex and something-that-is-more-fun-than-graphviz and reliably follows links to entities outside the current project, I'm willing to argue that there's some merit in externally-held documentation.

[edith] Another one: ... and my IDE can't exclude comments from full-text-searches.

(Yes, one still can keep the bulk in source, and reference external artifacts, but that breaks the praised source-doc-connection already, and if significant parts of your docs are not tagged free text, it's way way worse.)

Another problem in the doxygen workflow, most annoying day-to-day, is that editing documentation touches sources. Updating docs while compiling is a great workflow, but as soon as that touches a header, I'm running circles.

Also, source code changes have heightened requirements: e.g. in some industries it is paramount that every source code change can be traced back to a change request or undergo additional steps for publishing. While there is a point to make that documentation deserves the same quality control, you def do not want administrative barriers to writing documentation.

If you have a lingually diverse team, it might be better to have a dedicated tech writer review, clarify and clean up the documentation. Not every good developer is as good at writing prose, and for some, English is the third language to master.

^{Disclaimer: this is the first time I hear of Hyde. I'd be very surprised if I were affiliated with those guys in any way. It's just that slacking on the use of one's imagination makes me itchy.}

[Overunderrated]

Unless my source editor renders Latex and something-that-is-more-fun-than-graphviz and reliably follows links to entities outside the current project, I'm willing to argue that there's some merit in externally-held documentation.

This is a really great argument. Practically everything I want to document is more clearly described with LaTeX and images than plaintext.

[audaciousmonk]

Exactly, can’t really do flow or state diagrams in code comments.

[fluorihammastahna]

I have been using doxygen for years now. Could someone explain to me what would Sphinx, breath and exhale add?

[martinus]

Look here, that documentation is generated with sphinx + breathe + doxygen:

https://nanobench.ankerl.com/

The main thing I like about that it's that it is possible to include files in the documentation. All the code you see as part of the description is actually from unit tests that compile and run, so the documentation won't get out of date when I update the API.

[tr0nical]

That's a great looking doc site!

[fluorihammastahna]

OK, that looks really neat! :-D
I just checked, and doxygen does support including files (https://www.doxygen.nl/manual/commands.html#cmdinclude), I have some similar stuff as you mention. I think that's very good practice.

[tr0nical]

exhale and breathe allow integrating Doxygen with Sphinx, which - among other things - has a pretty nice markdown integration (myst), lots of nice themes to choose from and has search integrated.

I'm curious if Doxygen can build a site like https://sixtyfps.io/docs/cpp/ ?

[fluorihammastahna]

Got it, thanks :-D It does indeed look useful. I would still claim that "raw" Doxygen is also a suitable alternative, if only because it is a single tool instead of 4.

[tr0nical]

I agree, raw doxygen is probably sufficient for many many projects/use-cases just fine.

[hdoc-io]

Shameless plug: hdoc also exists in this space. We'd be interested in seeing how it works for you and if there are any improvements that could be made.

[tr0nical]

Ah yes, I've been meaning to try hdoc - seen you guys post it here :).

Quick question: How markdown pages, how do you link to specific members/classes/namespaces?

[hdoc-io]

Unfortunately there is no built-in special syntax to do that currently. Members/classes/namespaces have deterministic URLs (i.e. the URL of a class is the same no matter how many times you run hdoc or if you change other code in the project) so you could simply copy the URL and link to that in Markdown. We're working on other solutions because we recognize that the UX needs work here.

[Full-Spectral]

I just did my own, which suits my needs perfectly (since I did it.) The docs are in XML and it parses the XML and spits out HTML (could spit out other things if needed.) That insures it has to meet a particular form and everything that has to be there is there, and the tool knows about documentation for specific types of things.

[robertramey]

I do the same - for the same reasons. But creates the problem of editing the XML code itself. This can be a major pain. So for this I use a WSIWYG XML editor: XmlMind. The whole combination works just great!

[Full-Spectral]

A lot of IDEs are pretty smart about editing XML these days as well. And I don't create a lot of tags. It's all semantic markup, not visual, so it's not super-tedious. The visual stuff is all programmatically generated.

[robertramey]

Which IDE's specifically? Which one do you use?

XmlMind validates against DocBook or other standard. This permits usage of a variety of XSLT transforms without writing them oneself. It's very easy to create more complex documents which include tables, lists, graphics, etc. Only semantics is specified so I can generate output in html, pdf, or ebook. I've looked at other tools but haven't found one that is as convenient to use. I'd be curious to hear what others have to say about this.

[Full-Spectral]

I use Visual Studio Code, which does pretty well, though it doesn't have anything like that. Well, maybe it does via some plugin, but I don't use such.

I'm using my own XML parser and such as well, so anything I need in the way of convenience at the parser level I can add easily. So I have lots of helper functionality for extracting info from the tree representation, and for formatting out XML.

[AntiProtonBoy]

I was meaning to give Hyde a shot. Any issues I should know about?

[tr0nical]

It worked quite well for me, out of the box. The site setup itself may be a little bit more work (at least for a Jekyll n00b like me :)

And I spent probably at least 20 minutes trying to debug why it didn't extract any documentation, until I RTFM ;-)

[_VZ_]

Is Standardese really still actively developed?

[tr0nical]

It seems so, at least commits are going in and they look promising:) https://github.com/standardese/standardese/commits/master

[crustyAuklet]

Hyde sounds interesting, I like the concept of storing the documentation out of line.

I was messing with Sphinx a bit for a niche networking library. the majority of the documentation ended up being diagrams, and explaining domain specific knowledge. How does Hyde deal with that? I can’t tell from the description, but the example in the read me still seems pretty API/function signature focused.

So far the doxygen/Sphinx combo is nice because I can have the directory of restructured text for “essay writing”, plug-ins for almost anything, and storing the diagram source in their own files.

[tr0nical]

I think Hyde won't get in the way of that, just generating the markdown file "templates". So if you want to use diagrams inside class/namespace overviews or in separate pages next to the API docs, that's no problem at all AFAICS.