alandefreitas
commented
3 weeks ago One interesting thing I noticed about our gap analysis is that it also helps us better articulate why we're doing this. At first, the gap analysis included only a comparison of MrDocs with other tools. However, many people weren't really motivated because they didn't see the point in automating the documentation in the first place.
As we discussed these topics, we included this table in the analysis.
| Automatic | Manual | No Reference | |
|---|---|---|---|
| Nice for users | ✅ | ✅ | ❌ |
| Single Source of Truth / Less Work | ✅ | ❌ | ✅ |
| Always up-to-date | ✅ | ❌ | ❌ |
| No workarounds | ❌ | ✅ | ❌ |
MrDocs is going to solve the need for workarounds.
It ended up being good feedback, because I was comparing MrDocs with other tools for that, but I didn't care to justify automating the thing in the first place.
The point of automating the documentation is that there is a single source of truth for c++ declarations. Workarounds are bad because they subvert the single sources of truth (because of ifdefs just for docs).
When initially discussing this, I was counting the "single source of truth" as the "less work" category. But "Single source of truth" is a much better description of what's happening because it's also about being confident the documentation is always up to date regardless of how much work it is. Yes, less work is a consequence of that but single source of truth is more fundamental. It assures the reader of the docs that what they see is what they get.
This would be nice to go into the documentation “why automate”.
The other side of the "single source of truth" coin is having to maintain two things. And that's why Doxygen workarounds are so bad, because it effectively means we have to maintain two versions of the code: the well-formed and the ill-formed versions.
We need a higher-lever section in the documentation about the rationale preferring javadocs and automated extraction tools for producing a reference and not only how MrDocs compares to other tools.
C++ API design is challenging, hard to learn, and hard to teach. When you write a function signature, or declare a class, it is in that moment where you are likely to have as much information as you will ever have about what it is supposed to do.
In that moment it is best to write down some documentation because the more time passes before you do so, the less likely you are to remember all the details of what motivated the API in the first place. That is, the temporal adjacency of the C++ declaration to the documentation improves outcomes
Because the best engineers (and the worst) are naturally lazy, it is good to minimize the friction for writing the reference documentation of a declaration. For this reason, having the documentation be as close as possible to the declaration is ideal. In the same file and next to it. That is, the spatial adjacency of the C++ declaration to the documentation improves outcomes
When people write docs manually they duplicate the function signature which requires extra work. If the actual declaration changes and they forget to edit the docs, now the reference becomes out of date. For this reason it is best that when the C++ declaration changes the documentation is automatically updated. That is, the causal connection between the declaration and the generated documentation improves outcomes.
In summary, the automated extraction of reference documentation from C++ declarations containing attached javadoc comments is ideal because:
Ramey types will object, saying that Doxygen-generated references are shite. He's not wrong, but it is not because of the tool. Just like any other tool it depends on how you use it. Writing half-assed javadocs and then running Mr. Docs on code is not going to produce the best results. Just like C++ implementation and tests, you need to generate the resulting documentation for your declaration and then look at the rendered result. Then analyze it to ensure that what is shown is what you want the reader to see.
That is why we have the per-PR and branch document generation bots on GitHub. The review for every pull request which adds or modifies public declarations needs to include a look at the generated documentation, to ensure temporal adjacency.