Re: QML API docs for C++ wrapper types?
On Sonntag, 19. September 2021 19:43:46 CEST Carl Schwan wrote: > Le vendredi 17 septembre 2021 à 3:23 PM, Volker Krause a écrit : > > Hi, > > do we have an example somewhere how to do API docs markup properly for C++ > > wrappers for QML APIs? > > I don't think we have and it's currently with Doxygen a bit hard to do > something similar to the Qt documentation with a separate list of C++ types > and one of QML types (with a link from the QML types to the C++ types). > > I'm not sure that is the best way forward with this issue. This would be two > possibilities: > > * Use QDoc. There is already basic support for QDoc inside KApidox thanks to > Jannet. This would need more work and I'm not sure how stuff like > dependencies are handled. More importantly, moving to QDoc is a **lot** of > work to port the doc comments to the QDoc syntax and would need some work > in QDoc to also support doc comments inside .h files (I talked with > upstream during the Qt Contributor submit and they are fine with us adding > this feature as an option). > > * Continuing using Doxygen. This would be less work, we could use custom > doxygen commands for indicating in a unified way how to import the > component. More problematic would be the case of classes that can be used > from both QML and C++. Should we display in these cases the documentation > for both the QML usage and C++ usage? There are also issues that > documenting pure QML construct (attached properties, nested properties, > ...) is hard and the way this is currently done with DoxyQML is hacky and > probably would need first-class support in Doxygen. > > For now in your merge requests, I would probably put some information in > the readme/additional doc page that the library is usable from QML. Your > latest blog post about the Notification QML with some small changes could > be a great starting point for this. It's not perfect but at least it's > documented and can be found. Thanks for your input! I've applied your suggestion for KNotification now and added a slightly edited version of the blog post to the docs until we have something better. The same could probably also be done for KSyntaxHighlighting, and I'll try to come up with something along those lines for ki18n as well then. Regards, Volker > > Thinking about cases like these: > > https://invent.kde.org/frameworks/knotifications/-/merge_requests/49/ > > diffs#aa15f1228c0fb7ecaaa96bb9d8d843ef37033c2b_0_12 > > https://invent.kde.org/frameworks/ki18n/-/merge_requests/19/ > > diffs#31824e8758f678d4b04f3f329c208c8df64f5e25_0_33 > > https://invent.kde.org/frameworks/syntax-highlighting/-/blob/master/src/qu > > ick/ repositorywrapper.h#L20 > > > > How can I make those show up as they actually look like from a QML POV, > > ie. > > with their exported type names etc? > > > > Thanks, > > Volker signature.asc Description: This is a digitally signed message part.
Re: QML API docs for C++ wrapper types?
We have examples of where we have done this. Though I wouldn't necessarily use the word "properly". In Plasma-framework we have a manually made list where we can write the plugin name and list items by their exported QML type name. https://invent.kde.org/frameworks/plasma-framework/-/blob/master/src/declarativeimports/core/Mainpage.dox Which appears as: https://api.kde.org/frameworks/plasma-framework/html/core.html That links to the classic C++ generated docs, and we rely on users to know to only look at properties and signals.
Re: QML API docs for C++ wrapper types?
Le vendredi 17 septembre 2021 à 3:23 PM, Volker Krause a écrit : > Hi, > do we have an example somewhere how to do API docs markup properly for C++ > wrappers for QML APIs? I don't think we have and it's currently with Doxygen a bit hard to do something similar to the Qt documentation with a separate list of C++ types and one of QML types (with a link from the QML types to the C++ types). I'm not sure that is the best way forward with this issue. This would be two possibilities: * Use QDoc. There is already basic support for QDoc inside KApidox thanks to Jannet. This would need more work and I'm not sure how stuff like dependencies are handled. More importantly, moving to QDoc is a **lot** of work to port the doc comments to the QDoc syntax and would need some work in QDoc to also support doc comments inside .h files (I talked with upstream during the Qt Contributor submit and they are fine with us adding this feature as an option). * Continuing using Doxygen. This would be less work, we could use custom doxygen commands for indicating in a unified way how to import the component. More problematic would be the case of classes that can be used from both QML and C++. Should we display in these cases the documentation for both the QML usage and C++ usage? There are also issues that documenting pure QML construct (attached properties, nested properties, ...) is hard and the way this is currently done with DoxyQML is hacky and probably would need first-class support in Doxygen. For now in your merge requests, I would probably put some information in the readme/additional doc page that the library is usable from QML. Your latest blog post about the Notification QML with some small changes could be a great starting point for this. It's not perfect but at least it's documented and can be found. Cheers, Carl > > Thinking about cases like these: > https://invent.kde.org/frameworks/knotifications/-/merge_requests/49/ > diffs#aa15f1228c0fb7ecaaa96bb9d8d843ef37033c2b_0_12 > https://invent.kde.org/frameworks/ki18n/-/merge_requests/19/ > diffs#31824e8758f678d4b04f3f329c208c8df64f5e25_0_33 > https://invent.kde.org/frameworks/syntax-highlighting/-/blob/master/src/quick/ > repositorywrapper.h#L20 > > How can I make those show up as they actually look like from a QML POV, ie. > with their exported type names etc? > > Thanks, > Volker
QML API docs for C++ wrapper types?
Hi, do we have an example somewhere how to do API docs markup properly for C++ wrappers for QML APIs? Thinking about cases like these: https://invent.kde.org/frameworks/knotifications/-/merge_requests/49/ diffs#aa15f1228c0fb7ecaaa96bb9d8d843ef37033c2b_0_12 https://invent.kde.org/frameworks/ki18n/-/merge_requests/19/ diffs#31824e8758f678d4b04f3f329c208c8df64f5e25_0_33 https://invent.kde.org/frameworks/syntax-highlighting/-/blob/master/src/quick/ repositorywrapper.h#L20 How can I make those show up as they actually look like from a QML POV, ie. with their exported type names etc? Thanks, Volker signature.asc Description: This is a digitally signed message part.
