[Interest] [Doc] \include-ing qdoc documentation using snippet-identified cpp comments

[Ronan Jouchet]

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