The very first issues I ran into with this documentation project

There are basically three main issues:

Documenting C++20 (specifically: concepts)

At the time of writing, Hyde doesn’t support C++ concepts yet, which I plan to use extensively. The code still compiles (because clang can compile it) but Hyde ignores require statements. Its reaction to concept declarations isn’t tested.
The current behavior is that require does not show up in the declaration:

template <std::regular T>
class myClass;

simply appears in the API docs as:

template <class T>
class myClass;

which is a lot more generic and may not give a precise idea on what’s going on. It’s flat out wrong.

The OpenFOAM fork needs to compile with clang

Basically, any dependency code you rely on, as well as your own libraries, need to compile with clang. Foam-Extend, for example, doesn’t, since clang thinks some calls to operators between tmp objects are unambiguous.

Also, even with the forks which mostly compile with clang, they frequently use [[deprecated]] to make the compiler mark functions and methods as deprecated. But, they do not maintain the inline docs to match the deprecated docs.

Hyde actually sets compiler deprecation warnings as errors by default. We have to skip this step, and as a result we lose the automatic synchronization between code and API docs.

Linking to actual source files

Personally I don’t like to link API docs to actual source files, but it can be useful to those who don’t spend as much time in a CLI environment. I still think It’s the job of your IDE to show where stuff are, and to show you the documentation too though.

Hyde can generate source file relationships if we add -hyde-src-root to the call but this clutters the left sidebar with unwanted content; I process resulting markdown files with a Python script afterwards to minimize the clutter.

Because Hyde processes the expanded AST of C++ files, it doesn’t report line numbers for declarations and definitions for now.

Recap

The whole system can crumble very easily. And it might not even be your fault, so you couldn’t fix it! But while it works, it works marvelously well! Plus, it’s an opportunity for me to learn new things (Compiler AST, for example?).

• ←Previous
• Next→