This is a follow-up of mailing list thread [Interest][Doc] \include-ing qdoc documentation using snippet-identified cpp comments.

TL;DR: could qdoc officially support \include ing (using the 2 argument form of \include) qdoc documentation from snippet-identified text in any kind of file ? (rather than recommending all \include d doc comes from a .qdocinc file).

— Context / why this request —

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 one question and one change request to qdoc:

• 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 documentation and QTBUG-33046 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)