Hi.
I'm working to improve the usability/visibility of the high-level docs
(as opposed to generated, docstring-based per-method API documentation)
of an existing codebase.
Problem: documentation exists, but in README.md files scattered across
the codebase. It lacks visibility and makes it difficult to compile an
actual good-looking, tied together documentation.
Solution decided with the maintainers: start by having a `doc` folder.
Then, in order to keep the doc as close as possible from the code, I'd
only write scaffolding in the `doc` folder (structure, headings, etc.),
and `\include` the actual doc which I'd move from the README.md files
to comments in relevant cpp files, after md->qdoc conversion.
The doc<->code proximity sounds good, and I have a working prototype:
- Created a minimal `qdocconf`, defined `sourcedirs`
- Wrote a test.qdoc calling the snippetIdentifier-based \include:
\include path/to/some.cpp high-level-documentation
- Document at the start of some.cpp:
#include "some.h"
/*
//! [high-level-documentation]
Hey ho, this is \b{formatted high-level doc} from a \c .cpp file.
//! [high-level-documentation]
*/
I ran qdoc on this and it works, but I have two questions:
- Is this reasonable? Looking at the usages of `\include` in the
qt codebase, I was surprised not to see any similar usage.
`\include` seems only used to include `.qtdocinc` files to
avoid repetition. It's never used to directly include things
directly from cpp files, which to me sounds strange given how nice
it is to have high-level qdoc directly in my face when editing a cpp,
minimizing risks of code<->doc de-synchronization.
-> Isn't it? Or has it been tried and there be dragons?
Any better way to do what I want to do?
- The doc [1] and QTBUG-33046 [2] recommend using a .qtdocinc
file extension. Obviously, that doesn't cover my use case.
-> Any chance to see this recommendation removed and my use case
recognized? (It would be sad to see this become a requirement
and see qdoc 5.7 or 5.8 plain refuse my `\include foo.cpp`)
Thanks!
[1]
http://doc.qt.io/qt-5/12-0-qdoc-commands-miscellaneous.html#2-argument-form
[2] https://bugreports.qt.io/browse/QTBUG-33046
--
Ronan
_______________________________________________
Interest mailing list
Interest@qt-project.org
http://lists.qt-project.org/mailman/listinfo/interest
