QML API docs for C++ wrapper types?

[Volker Krause]

On Sonntag, 19. September 2021 19:43:46 CEST Carl Schwan wrote:
> Le vendredi 17 septembre 2021 à 3:23 PM, Volker Krause <vkrause at kde.org> 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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 195 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20210920/9a0160f6/attachment.sig>