AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: Add \examplecategory macro

Browse Source 
Examples in Qt's codebase must be tagged with specific categories
such that Qt Creator can group them thematically. This can be done
by way of using the `\meta category` construct in QDoc.

At the same time, we want the generated documentation to group the
examples by the same logic as in Qt Creator. Hence, QDoc was modified
to implicitly add a group for each category that is used in a
`meta category` invocation.

By design, QDoc exposes ways to list groups to users, but no way to list
the \meta command invocations. Letting QDoc implicitly add a group for
categories passed to the \meta command as a side-effect, therefore breaks
with the principle of least surprise and the single responsibility
principle.

An alternative solution makes use of QDoc's existing support for code
generation through macros. This patch introduces the macro
`\examplecategory` as a global macro throughout Qt to achieve the same
effect as the aforementioned change to QDoc. The macro takes an argument
enclosed in curly braces. This argument is the example category name. It's
used as meta information in the manifest files consumed by Qt Creator, and
added as the category group name for the QDoc side at the same time.

The introduction of this macro allows reverting the change to QDoc
itself, while maintaining feature parity for both Qt Creator and the
generated content.

Task-number: QTBUG-111891
Pick-to: 6.5
Change-Id: I311b98168253b45ac456ff3c1824db3d835191a9
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
This commit is contained in:
Paul Wicking 2023-03-29 13:33:28 +02:00
parent 5a334b3d2b
commit 2f35879649
1 changed files with 1 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/global/macros.qdocconf
View File

@ -54,6 +54,7 @@ macro.pi.DocBook = "&#928;"
macro.beginqdoc.HTML = "/*!"
macro.endqdoc.HTML = "*/"
macro.borderedimage = "\\div {class=\"border\"} \\image \1\n\\enddiv"
macro.examplecategory = "\\meta category {\1}\n\\ingroup {category \1}"
macro.beginfloatleft.HTML = "<div style=\"float: left; margin-right: 2em\">"
macro.beginfloatright.HTML = "<div style=\"float: right; margin-left: 2em\">"