[Development] qdoc for C++ and QML

[Sean Harmer]

Hi,

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.

> Regarding the creator issue, I don't understand the problem so I can't comment.

Like when building a C++ project in creator and being told by the 
compiler there are warnings/errors, creator parses these into issues 
that are nicely displayed and when you click on them take you to the 
relevant section of the code.

Cheers,

Sean

>
> martin
> ________________________________________
> From: Development <development-bounces+martin.smith=qt.io at qt-project.org> on behalf of Sean Harmer <sean.harmer at kdab.com>
> Sent: Monday, April 24, 2017 3:05:17 PM
> To: development at qt-project.org
> Subject: [Development] qdoc for C++ and QML
>
> Hi,
>
> are there any plans to reduce/remove the redundancy when writing
> documentation for both C++ and QML? Seems a waste of time to have to
> copy/paste or update the docs twice for both languages when really the
> only things differing are the "Q" prefix on the class names in C++.
>
> On a related note, are there any plans to be able to run make
> docs/html_docs/qch_docs etc from within creator and have the issue
> reporter plugin parse the output? Being flooded with warnings about
> overwriting HTML files on the command line and tryign to spot genuine
> issues is not much fun.
>
> Cheers,
>
> Sean
> --
> Dr Sean Harmer | sean.harmer at kdab.com | Managing Director UK
> KDAB (UK) Ltd, a KDAB Group company
> Tel. +44 (0)1625 809908; Sweden (HQ) +46-563-540090
> Mobile: +44 (0)7545 140604
> KDAB - Qt Experts
> _______________________________________________
> Development mailing list
> Development at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development
> _______________________________________________
> Development mailing list
> Development at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development
>