On 20.08.24 13:33, Ben Cooksley wrote:
On Tue, Aug 20, 2024 at 8:07 AM Nicolas Fella <nicolas.fe...@gmx.de>
wrote:
On 09.07.24 18:37, Nicolas Fella wrote:
> Hi,
>
> while reviewing our API documentation I noticed an increasing
amount of
> brokenness in it. Not even in the content, but the way it is
presented.
>
> Doxygen seems to struggle to properly parse and document some
new-ish Qt
> features:
>
> - It doesn't parse signals declared with Q_SIGNAL (as opposed to
> Q_SIGNALS:) as such, so there will be a stray "Q_SIGNAL" in the
page and
> the function not marked as a signal. This can be seen e.g. at
>
https://api.kde.org/frameworks/kcmutils/html/classKPluginModel.html#a6c3d36e9c38730cc1e6f6697d2253600
>
>
> - It doesn't handle the declarative type registration macros
> (QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON etc) correctly,
so they
> randomly show up in the documentation. See e.g.
>
https://api.kde.org/frameworks/kirigami/html/classKirigami_1_1Platform_1_1IconSizes.html#ad87aa092b90a9d8a2cb2464775c2e370
>
>
> Then there's the general problem with doxygen not natively
supporting
> QML. We work around this with doxyqml, which translates QML
files into
> C++-ish files that then get processed by doxygen. That works
okay, but
> is far from ideal. For example:
>
> - C++ types and QML types are listed side-by-side on the
website, with
> no clear distinction between those
>
> - QML types that are defined in C++ aren't properly indicated as
QML API
> and their documentation shows lots of irrelevant functions like
property
> getters/setters
>
> - Some property types are not displayed correctly, e.g.
list<T.Action>
> is displayed as listTAction:
> https://api.kde.org/frameworks/kirigami/html/classCard.html
>
> - QML-specific concepts like attached properties are not supported
>
> - Types that are usable from QML *and* C++ aren't marked as such
>
> - alias properties don't have their type in the documentation
>
> - The page doesn't show the QML import name to be used to import
the type
>
> Generally browsing the documentation for Qt's own QML types
feels vastly
> better than e.g. Kirigami's documentation.
>
> What can we do about this? While some of these problems could
likely be
> addressed by better markup or upstream work on doxygen and
doxyqml I'm
> afraid it will always be an uphill battle to get doxygen to nicely
> document Qt-specific concepts. From my own experience I can say that
> contributing even small improvements to our documentation markup
doesn't
> feel rewarding given the overall poor state of the system.
>
> Qt maintains its own documentation tooling, qdoc, which is
> (unsurprisingly) much better at documenting Qt-specific concepts and
> QML. qdoc is actively maintained, well documented, and in my
experience
> pleasant to use. From past discussions I gather that the primary
> objection to qdoc is that it requires documentation comments to
be in
> the source files instead of the headers. For this reason I am
working on
> a qdoc patch to allow the documentation to be contained in
header files:
> https://codereview.qt-project.org/c/qt/qttools/+/574401
>
> With this in mind I propose that we migrate out API
documentation from
> doxygen to qdoc. Since the markup is using slightly different
> syntax/keywords there will be some work involved, but the concepts
> usually map so that work is at least semi-automatable. While
there will
> be a medium amount of manual labor involved I firmly believe the
result
> will be worth it by having much better documentation especially
for QML
> types.
>
> Thoughts on my proposal?
Hi,
I implemented a proof-of-concept for converting our documentation to
qdoc and generating pages from it.
Due to the way qdoc works it makes sense to integrate the
documentation
generation into the build system.
https://invent.kde.org/frameworks/extra-cmake-modules/-/merge_requests/457
adds API for this to ECM.
https://invent.kde.org/frameworks/kcoreaddons/-/merge_requests/443
shows
how it is used as well as the markup changes needed.
https://invent.kde.org/sysadmin/ci-utilities/-/merge_requests/354 adds
tooling for generating the documentation for all modules, which will
eventually become a periodic CI job.
https://invent.kde.org/nicolasfella/doc-includes contains common
configuration that is included from all modules. This could eventually
live in e.g. kapidox.
For both sysadmin/ci-utilities and doc-includes another potential
place for this to live would be websites/api-kde-org which is where
the existing logic to build api.kde.org <http://api.kde.org> is based.
The actual website generation could also live in websites/api-kde-org. I
added it to ci-utilities because it uses the python stuff in there for
the package registry, but that could be solved differently.
doc-includes or however it ends up being named should probably be a
standalone thing similar to kapidox since it will also be relevant for
people generating docs locally or as part of distro builds (for QCH).
You can see it in action at
https://nicolasfella.de/docs/kcoreaddons-module.html. There's
still some
minor things to be ironed out, but overall it looks promising to me.
Indeed, looks quite promising. This will end up fully replacing
KApiDox I assume?
That's a good question. Ideally we would only have one way of doing API
docs. Converting all of Frameworks is something that should be doable
fairly quickly. However there's also a number of other documented
libraries that would need converting too. Not sure how long that would
take. We may or may not want to consider some sort of hybrid solution
that integrates the old and new approach.
