The state of our API documentation and what to do about it

[Albert Astals Cid]

El dimarts, 9 de juliol del 2024, a les 18:37:16 (CEST), Nicolas Fella va 
escriure:
> 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#a6c3d36e
> 9c38730cc1e6f6697d2253600
> 
> - 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_1Ic
> onSizes.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

Without having fully read the email this was going to be my question.

If this gets fixed, I "don't care" if we use doxygen or qdoc.

Cheers,
  Albert

> 
> 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?
> 
> Cheers
> 
> Nico