Show HN: A modern documentation tool for C++ and a replacement for Doxygen
1–10 of 14 posts
Re: Show HN: A modern documentation tool for C++ and a replacement for Doxygen
#2C++ 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.
Re: Show HN: A modern documentation tool for C++ and a replacement for Doxygen
#3Took 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.
Re: Show HN: A modern documentation tool for C++ and a replacement for Doxygen
#4I'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.
Re: Show HN: A modern documentation tool for C++ and a replacement for Doxygen
#5At 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...
Re: Show HN: A modern documentation tool for C++ and a replacement for Doxygen
#6Took 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 com…
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.
Re: Show HN: A modern documentation tool for C++ and a replacement for Doxygen
#7I'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.
Re: Show HN: A modern documentation tool for C++ and a replacement for Doxygen
#8At 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.
Re: Show HN: A modern documentation tool for C++ and a replacement for Doxygen
#9[deleted]
Re: Show HN: A modern documentation tool for C++ and a replacement for Doxygen
#10I'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.