API dox: document Q_DECLARE_FLAGS-based flags
ClosedPublic

Authored by kossebau on Apr 19 2020, 4:56 PM.

Details

Summary

KApiDox & ECMAddQch have been just teached about Q_DECLARE_FLAGS, so the
underlying typedefs are no longer skipped by doxygen, but can be
documented now, allowing links to be generated for these types e.g. when
used as arguments.

The "#" prefix to the enum name in the description text of all the
Q_DECLARE_FLAGS docs seems needed to properly trigger doxygen autolinks.

Diff Detail

Repository
R244 KCoreAddons
Branch
documentFlags
Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 25474
Build 25492: arc lint + arc unit
kossebau created this revision.Apr 19 2020, 4:56 PM
Restricted Application added a project: Frameworks. · View Herald TranscriptApr 19 2020, 4:56 PM
Restricted Application added a subscriber: kde-frameworks-devel. · View Herald Transcript
kossebau requested review of this revision.Apr 19 2020, 4:56 PM
dfaure added inline comments.Apr 19 2020, 5:18 PM
src/lib/jobs/kjob.h
99 ↗(On Diff #80562)

Inexperienced developers might be confused by the OR in there.
In English it sounds like exclusive or, while the whole point of Q_DECLARE_FLAGS is that multiple flags can be set at the same time.

Why not just say "Stores a combination of" ?

kossebau added inline comments.Apr 19 2020, 5:30 PM
src/lib/jobs/kjob.h
99 ↗(On Diff #80562)

I had myself inspired by the wording of https://doc.qt.io/qt-5/qflags.html and similar of Qt docs for flags like https://doc.qt.io/qt-5/qwidget.html#RenderFlag-enum, which currently also talk about
"The QFlags class provides a type-safe way of storing OR-combinations of enum values"
or
"The RenderFlags type is a typedef for QFlags<RenderFlag>. It stores an OR combination of RenderFlag values."

But I tend to think you have a point, the OR here is not really needed and rather confusing, Will update.

kossebau updated this revision to Diff 80569.Apr 19 2020, 5:33 PM

drop the "OR" from "OR combination"

If okay, I would walk over the other KF modules and apply the same pattern there as well, once this here is accepted.

dfaure accepted this revision.Apr 19 2020, 5:35 PM
This revision is now accepted and ready to land.Apr 19 2020, 5:35 PM
This revision was automatically updated to reflect the committed changes.