QML API docs for C++ wrapper types?

[Carl Schwan]

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.

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