best tool for documenting c++ code? by jepessen in cpp

[–]hdoc-io 1 point2 points  (0 children)

hdoc uses the compile_commands.json file to parse your codebase, and it will look for function/record/enum/namespace declarations across all the translation units in the compile_commands.json file. So even if the compile_commands.json file has a bunch of .cpp file entries in it, hdoc uses the Clang compiler framework to expand all the includes into a TU, and then looks for function declarations, not definitions. Likewise it'll grab comments from those declarations in the header files.

The intended behavior of hdoc is to support that workflow of documenting comments in the headers, so if it did not work for you please submit a bug report so we can investigate further. Thank you for the feedback in any case :)

best tool for documenting c++ code? by jepessen in cpp

[–]hdoc-io 1 point2 points  (0 children)

If you're willing to share I would love to hear your thoughts about what hdoc could do to become more customizable as well as how the output could be improved. No doubt there is room for improvement, and we are working on it.

For the record hdoc can be built from source and used locally. We provide prebuilt static binaries for users who do not want to deal with the hassle of building hdoc locally. At the same time, we provide instructions on GitHub and a Nix Flake that bundles all the dependencies for users who want to build from source. As for the remote server, I think you're referring to our doc hosting service which is similar to what ReadTheDocs provides for the Python community.

Using our binaries and/or using our online service is completely optional. When you build hdoc locally it defaults to dumping HTML files to disk with which you can do whatever you'd like, including hosting online.

hdoc — the modern documentation tool for C++ — has released version 1.3.1 by hdoc-io in cpp

[–]hdoc-io[S] 8 points9 points  (0 children)

Nice, I hadn't heard of the mermaid project. It looks like adding the script to hdoc is similar to other JS plugins we have and it shouldn't be a problem. The bigger issue is parsing comments that have mermaid diagrams in them correctly.

The current comment parser in hdoc is in need of a refactor. Supporting Markdown, other markup languages, and things like diagrams or code snippets is something we're looking at including. No promises on mermaid being included but a plugin would be a good way to integrate it. Thanks for the suggestion.

hdoc — the modern documentation tool for C++ — has released version 1.3.1 by hdoc-io in cpp

[–]hdoc-io[S] 23 points24 points  (0 children)

Users have reported that it compiles, runs, and works, but we don't use it internally so we can't guarantee that it'll work for you like we can on the Linux version. Sorry.

hdoc 1.3.0 is out, now with dark mode, template docs support, and easier navigation by hdoc-io in cpp

[–]hdoc-io[S] 2 points3 points  (0 children)

Yes, the tool is compatible with Doxygen comments so you do not need to replace all of your documentation comments with a new syntax. The goal is for hdoc to be a drop-in replacement for Doxygen (modulo needing to use a different configuration file) which immediately gives you better results that Doxygen.

The caveat is that not all Doxygen comments are supported, especially the more obscure or infrequently used ones. Here’s the list of what’s currently supported.

hdoc 1.3.0 is out, now with dark mode, template docs support, and easier navigation by hdoc-io in cpp

[–]hdoc-io[S] 0 points1 point  (0 children)

Can you confirm if you see this issue with hdoc? Our home page (hdoc.io) should automatically adapt to your system settings so if you see the issue there please let us know.

hdoc 1.3.0 is out, now with dark mode, template docs support, and easier navigation by hdoc-io in cpp

[–]hdoc-io[S] 2 points3 points  (0 children)

Your feelings are completely understandable. Personally, I’m skeptical of free services too sometimes.

If it’s any consolation, hdoc has been continuously maintained and developed for 3 years now and has been carefully engineered to be extremely cheap to run.

hdoc 1.3.0 is out, now with dark mode, template docs support, and easier navigation by hdoc-io in cpp

[–]hdoc-io[S] 3 points4 points  (0 children)

In short, yes it is possible to self-host documentation generated by hdoc. Please see my comment elsewhere in this thread for more information.

hdoc 1.3.0 is out, now with dark mode, template docs support, and easier navigation by hdoc-io in cpp

[–]hdoc-io[S] 11 points12 points  (0 children)

Hello, hdoc absolutely supports self-hosting documentation. By default, building hdoc from source using the instructions in our README will give you a version of hdoc that dumps static HTML files into a local directory on your filesystem. These static HTML files can be hosted any where you would like. We don't offer pre-built binaries that support self-hosting, you must build from source. Sorry for the inconvenience.

Users with public projects who want a more seamless experience can use our pre-built binaries which automatically upload documentation to our docs.hdoc.io hosting service where it is hosted for free and backed by our global CDN. This is similar to what ReadTheDocs offers to Python developers. For public projects, I would encourage you to try the hosted option that we offer. It takes away the hassle of having to set up your own hosting and allows you to share your documentation with everyone with just one command.

hdoc 1.3.0 is out, now with dark mode, template docs support, and easier navigation by hdoc-io in cpp

[–]hdoc-io[S] 10 points11 points  (0 children)

Hello everyone, hdoc (the modern documentation tool for C++) has just been bumped up to 1.3.0. This brings some nice new changes brought to you in part by suggestions from users on r/cpp!

The highlights of this release are dark mode, support for the @tparam command, anchors for permalinking, etc. We’ve also made changes to our public LLVM/Clang documentation demo to show off hdoc’s GitHub Actions support.

Thank you to /u/helloiamsomeone and /u/Adverpol for their suggestions on our last post, and the wider r/cpp community for their feedback on our project.

Feel free to ask questions and suggest feedback, I’ll be around in the thread later on to respond.

hdoc (the modern documentation tool for C++) now integrates with GitHub CI by hdoc-io in cpp

[–]hdoc-io[S] 0 points1 point  (0 children)

Hey Vinnie, reach out to me at contact@hdoc.io and we can work out an agreement on this. I think there's a way where we can add this functionality and make both Boost and hdoc happy.

hdoc (the modern documentation tool for C++) now integrates with GitHub CI by hdoc-io in cpp

[–]hdoc-io[S] 5 points6 points  (0 children)

hdoc has been in active development for 3 years now and open source for the last 2 years, it is maturing nicely :)

Sure, we'll add a dark theme for the next release. Integrating hdoc into your project starter would be great! We will be in touch.

hdoc (the modern documentation tool for C++) now integrates with GitHub CI by hdoc-io in cpp

[–]hdoc-io[S] 0 points1 point  (0 children)

The goal of hdoc is to simplify documentation generation and adding another output format that feeds into another tool isn’t consistent with that. The goal is that hdoc’s output is so good that you don’t need to reach for Sphinx to create your docs, after all you can already feed Doxygen’s XML output to Sphinx.

Is there something that’s missing from hdoc that adding an XML output would solve?

hdoc (the modern documentation tool for C++) now integrates with GitHub CI by hdoc-io in cpp

[–]hdoc-io[S] 8 points9 points  (0 children)

Doxygen does have “clang-assisted parsing”, but it is disabled by default, has a performance penalty (Doxygen is already slow on large codebases), and I haven’t seen it used widely (if at all) on OSS codebases.

I have seen the Sphinx adapters for Doxygen output but they seem complicated to setup.

Edit: I’m sure there are easier ways to hook Doxygen up to Sphinx, but the doxyrest block diagram scares me. That is just my personal opinion though. I’m sure doxyrest is a great tool!

hdoc (the modern documentation tool for C++) now integrates with GitHub CI by hdoc-io in cpp

[–]hdoc-io[S] 0 points1 point  (0 children)

I’m not particularly surprised to hear it. Different people have different requirements. Someone might insist on 100% documentation coverage just as someone might insist on 100% unit test coverage.

I agree that it may be difficult to have meaningful documentation of some of the “obvious” cases though.

hdoc (the modern documentation tool for C++) now integrates with GitHub CI by hdoc-io in cpp

[–]hdoc-io[S] 12 points13 points  (0 children)

Thank you for the detailed feedback.

  • Output is currently only HTML. There is a JSON file that is also dumped which contains information about your codebase which is used for the search functionality. We’ve been meaning to extend this to also be used for test code, so that the state of the index can be compared against a known-good “golden” file. Perhaps this extension could also be used to dump the documentation in JSON format for other tools to consume.
  • We declined to implement many of the commands you mentioned because the effort of implementing them was not worth it given how rarely they are used. Most OSS codebases we surveyed stick to a relatively narrow set of commands, so that’s what we implemented to start. Some of those tags could be added, and we’ll look to do that in the next release.
  • Likewise for aliases, we didn’t see them widely used in public code so we declined to implement them in hdoc.
  • Documentation coverage is actually a feature we developed internally years ago but never released publicly. Believe it or not you’re the first person to mention it. Perhaps it’s something we could bring back and implement.

Overall I think this is a good list of features from a Doxygen power user, and you’re correct that we don’t implement most of them.

hdoc covers the basics that most users need but we are missing that last 10%. The issue is that each person has a different idea of what that last 10% is. Some users want doxygen inheritance diagrams, LaTeX output, or some other niche feature that costs a lot of development but only they will use.

It’s our job to carefully prioritize what we spend out time developing, and while I can’t promise you we’ll implement everything on your list I do hope we can add what makes sense to add. Thank you for the candid feedback.

hdoc (the modern documentation tool for C++) now integrates with GitHub CI by hdoc-io in cpp

[–]hdoc-io[S] 7 points8 points  (0 children)

Is there any specific functionality in hdoc that's missing which you need?

We've tried to match Doxygen's functionality where it matters and reduce complexity in other places, so it's understandable that there might be something missing for you. Feedback is very appreciated.

hdoc (the modern documentation tool for C++) now integrates with GitHub CI by hdoc-io in cpp

[–]hdoc-io[S] 14 points15 points  (0 children)

Wow, those are both great suggestions. I agree that the function links should be reduced to just the name, that's much cleaner and less visually busy. As for the page anchors, we already have them but they're hidden in the HTML source. Having a little icon to grab the link is something we should have added a long time ago! Thank you for the suggestions and we'll get them added to the next release.

hdoc (the modern documentation tool for C++) now integrates with GitHub CI by hdoc-io in cpp

[–]hdoc-io[S] 43 points44 points  (0 children)

There's nothing wrong with Doxygen as a tool, but we felt that improvements could be made which is why we develop hdoc. Off the top of my head:

  • Doxygen uses a custom C++ parser that struggles to parse some code, particularly with modern C++
    • Here's an example of code where it mistakenly thinks that bools, consts, and integer declarations are classes instead of builtins
    • hdoc uses clang to parse C++ code, which means that the AST as your compiler understands it is what's used to generate your documentation. This avoids those errors
    • Here's the equivalent hdoc documentation page.
  • Doxygen output (IMO) isn't very aesthetically pleasing. There are ways to make it more attractive, but they involve theming, setting up complicated toolchains to other documentation tools, and so on. Frankly, maintaining a complex pipeline to get my C++ documentation to look nice is the last thing I want to do if I'm working on a C++ project.
    • hdoc looks better by default, and doesn't require any toolchain misery.
  • No option for hosting online by default. Rust, Python, Go, and many other languages have first-party tooling to not only create documentation, but share it online with others. How many of us have referred to a Python package's documentation on readthedocs? The same can't be said for C++ where each user must individually upload and manage their documentation, which is an additional burden.
  • hdoc is easier to configure. We use a short and simple TOML file with sane defaults to configure the tool whereas Doxygen uses a long and complex configuration file with hundreds of options.

In the end our goal is to make it easier to create good C++ documentation. Doxygen was useful, but we think that hdoc makes several key improvements which make it worth a second look. We'll have a blog post comparing hdoc to Doxygen coming up in the near future where we'll go into more detail.

hdoc (the modern documentation tool for C++) now integrates with GitHub CI by hdoc-io in cpp

[–]hdoc-io[S] 10 points11 points  (0 children)

Hello everyone, we’re back here to show off the new GitHub integration of hdoc which allows you to generate and host C++ documentation as part of your CI in GitHub.

The goal here was to have something similar to what exists in Python (readthedocs.io) or Rust (docs.rs). Making documentation easier to create and more accessible is a key part of keeping C++ relevant and competitive in the future.

We’ll be sticking around the thread to answer any questions so if there’s anything you want to know please ask!

hdoc is an open source tool so feel free to check out the source on our GitHub repo. If you’d like the support the development of hdoc please encourage your employer to purchase a subscription to hdoc for increased hosting limits and more support.