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 <[email protected]> on behalf of Sean Harmer <[email protected]> Sent: Monday, April 24, 2017 4:17:58 PM To: [email protected] 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 <[email protected]> on > behalf of Sean Harmer <[email protected]> > Sent: Monday, April 24, 2017 3:05:17 PM > To: [email protected] > 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 | [email protected] | 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 > [email protected] > http://lists.qt-project.org/mailman/listinfo/development > _______________________________________________ > Development mailing list > [email protected] > http://lists.qt-project.org/mailman/listinfo/development > _______________________________________________ Development mailing list [email protected] http://lists.qt-project.org/mailman/listinfo/development _______________________________________________ Development mailing list [email protected] http://lists.qt-project.org/mailman/listinfo/development
