[Development] qdoc for C++ and QML
Shawn.Rutledge at qt.io
Tue Apr 25 08:16:27 CEST 2017
> On 24 Apr 2017, at 16:17, Sean Harmer <sh at theharmers.co.uk> wrote:
> On 24/04/2017 14:23, Martin Smith wrote:
>> Regarding documenting both C++ and QML at the same time, I will be happy to implement it if we can get a good idea for how to do it.
> Well, take https://codereview.qt-project.org/#/c/192093/ as a case in point. The docs for the QML and C++ parts are 80% the same. The only difference really is the code samples. So perhaps one option would be to allow specifying code blocks and maybe other blocks as being specific to C++ or QML. The rest of the containing block could then be the same.
> Likewise for \property vs \qmlproperty sections. The only difference is a "Q".
> When writing the docs perhaps marking up a class name without the "Q" prefix could link to the class docs in C++ and the QML type in the QML docs. So instead of:
> "A QFoo can be used to do blah" in C++ vs
> "A Foo can be used to do blah" in QML, we could have something like:
> "A \type Foo can be used to do blah" then when generating the C++ docs it looks for the QFoo docs.
This we haven’t addressed yet, right? Sounds like we need conditionals in doc comments: if building the QML doc, do this, if C++ do that.
The code samples could be put into snippets though, to keep those comment blocks from getting unwieldy.
More information about the Development