Show HN: A modern documentation tool for C++ and a replacement for Doxygen | Hacker News Reader

Show HN: A modern documentation tool for C++ and a replacement for Doxygen

hdoc.io

31 pointshdoc12 comments

C++ is falling behind in the quality of documentation output compared to what tools like rustdoc, ReadTheDocs, and godoc generate. Getting good output from existing C++ tools requires disproportionate effort that could be better spent elsewhere. Furthermore, existing tools have a hard time dealing with modern C++.

We made hdoc to solve these problems: prioritizing the quality of output, making the developer experience seamless, and retaining compatibility with existing best practices.

hdoc lets you generate reference API documentation and put supporting guides, tutorials, how-tos right alongside your other docs. We have a sample of what hdoc's output for LLVM+Clang: https://docs.hdoc.io/hdoc/llvm-project/. The source for the repo is available here: https://github.com/hdoc/llvm-project/

Use the code HDOC-HN-LAUNCH for your first three months free when you sign up. 5 codes are available.

I've been programming and documenting large projects with sphinx and doxygen for years now and I really don't see the appeal or the problem this solves. Bad documentation is because of lazy programmers. Nothing more, nothing less. If someone is actually able to keep up with the myriad changing C++ standards, not to mention testing practices and frameworks, documentation is not hard in comparison at all. What is often missing is incentives to write documentation, again not something this solves. As for markdown, that's easy to implement with Sphinx anyway. I wrote a series of posts on documenting modern c++ a while ago [1]. There are some fantastic free tools out there, which also allow doctests.

[1] https://rgoswami.me/posts/doc-cpp-dox-sph-exhale/

I agree that bad documentation is often due to lack of effort. Many developers don't like writing documentation, which is unfortunate because bad documentation can drag down otherwise great projects. If I'm evaluating two libraries and one has great docs and the other has awful docs, you know which one I'm picking.

Likewise, hdoc isn't instantly going to make an engineer spring up and say "I'm going to write documentation!". No tool is going to do that. hdoc is meant to simplify and streamline the process of writing documentation. Current tools disincentivize writing documentation. If you need to spend a day cobbling together 5 different tools and themes to set up a documentation page for your project you might not be as eager to do it as you would be if you could write a five line configuration file and run a single binary.

No doubt there are free tools that can produce decent output. However, all of them require considerable effort that could be spent writing code or documentation. Others don't support modern features, or completely fail to process basic C++ code. Clearly a market for a tool which solves these problems exists, there is no shortage of people asking about Doxygen alternatives or better ways to document their C++ code. Lastly, there are companies in other communities which provide a similar services, for instance ReadTheDocs.com which has documentation and managed hosting for Python projects.

ReadTheDocs.com is largely the de-facto standard for Python projects because it is free to use. Since a lot of developers have experience with it, in production too, it is often used as a host (even though it is sub-par as a web-host and CI service). For a product which seems to have been trademarked in 2019, not having a free-plan or more importantly, one for FOSS projects, means this is at best, a niche option. Additionally, being proprietary and closed source means it will be difficult to integrate into multi-language programs. Doxygen is a good standard, which works across multiple languages, and its reach is augmented by Sphinx with inter-sphinx. In the domain I work (scientific software), very few tools are written in pure C++.

By the way, I hope my comments are not taken as anything other than constructive criticism.

Took me a while to find the markup supported by hdoc: https://hdoc.io/docs/features/api-docs/

"hdoc supports a small subset of Doxygen's commands. hdoc supports both the @ and \ conventions for commands, meaning you can use @brief or \brief interchangeably."

As far as I can tell, it supports just 3 commands: @brief, @param, @returns. Any plans to support @tparam for template parameters? It's the one other doxygen command that I use frequently for C++ code.

When we originally implemented the Doxygen command support we looked at the most used commands in the code bases we profiled, and settled on about five, which we cut down to those three. Support for more commands is on the roadmap as we look to cover more of the Doxygen spec. This is a reasonable thing to have that many people would find useful, we just didn’t focus on it for the MVP.

I'm surprised there isn't cross-linking amongst types? If the function listing is `Foo bar(const Baz& x) const` I'd expect `Foo` and `Baz` to be links to those type definitions.

Yes, this is one of the many improvements we plan on adding soon. It was cut from the MVP because we wanted to ensure that it was 100% accurate. Complex code bases can be ambiguous and it would be a disservice if the user clicked on one of these crosslinks and it took them to the wrong symbol.

At first sight, it looks more modern than Doxygen. But a tool is just a tool, and what really counts is the quality of the documentation itself. Entries like this one are not very useful:

https://docs.hdoc.io/hdoc/llvm-project/fBE2A174F6C7A57F0.htm...

LLVM/Clang are generally well-documented but there are places that don’t have great coverage.

Unfortunately tools are only part of the solution. Our goal with hdoc is to make writing documentation easier and to make it easier to create great/cohesive output. If engineers perceive writing documentation as too laborious they’ll be unlikely to do it, so we hope that hdoc’s workflow and results help.

I'm not one of those "everything should be open source and free" snobs, but my documentation tool is definitely one of them. This is a SaaS behind a paywall it seems, so it's immediately not winning any points for me.

I do agree that the existing tools are horribly subpar, but at least I don't need to contact support to fix them myself.

You're going to have a hard time convincing the larger C++ community to use this, I think. Companies, sure, I guess.

EDIT: Also I kind of reject one of the assertions made here; the reason why I never have documentation for my libraries isn't because I don't write it. It's there, very nicely laid out, in the headers and comments and whatnot. A lot of it. Enough to fully understand it. But rendering it out to Man pages, Markdown, HTML, etc. in a manner consistent with how those formats should work is a PITA that Doxygen simply doesn't do how I'd like.

We're looking at open sourcing hdoc in the future, and at least offering a free plan in the near term. We'd like to give back to the community too, it's part of the reason why we host our LLVM documentation freely.

We're currently targeting businesses and charging for the product understandably presents a barrier to many people, especially in C++ land where open source is the de facto standard. Unfortunately open source tools don't make money.

How would you like your documentation to be rendered when it's processed into markup formats? Source code documentation largely hasn't changed since the introduction of Doxygen-style comments so I'm curious to hear about your approaches.

Reply on news.ycombinator.com