[Development] qdoc for C++ and QML

[Martin Smith]

The problem when combining C++ and QML documentation is qdoc has no way of knowing whether a QML type exists for a C++ class or whether a C++ class exists for a QML type.

Should we add a new command like \cpp-qml to indicate that both exist and are documented the same?

And if a C++ class has a corresponding QML type, should every member function be included in the documentation for both? How will qdoc know that a member function only applies to the C++ class or only to the QML type?

martin
________________________________________
From: Development <development-bounces+martin.smith=qt.io at qt-project.org> on behalf of Sean Harmer <sh at theharmers.co.uk>
Sent: Monday, April 24, 2017 4:17:58 PM
To: development at qt-project.org
Subject: Re: [Development] qdoc for C++ and QML

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
>
_______________________________________________
Development mailing list
Development at qt-project.org
http://lists.qt-project.org/mailman/listinfo/development