diff options
author | Luca Di Sera <luca.disera@qt.io> | 2024-01-08 10:46:59 +0100 |
---|---|---|
committer | Luca Di Sera <luca.disera@qt.io> | 2024-01-17 15:36:26 +0100 |
commit | 957786ee4bc5a7b1c183cf3e02538e5022d2d462 (patch) | |
tree | add1afded76118eaecb98010f75b8591b82621d8 /src/quickcontrols | |
parent | 9c1adc5e2cc02af59df62285c20b8258fa040320 (diff) |
Doc: Avoid duplicate ids in styling macros
The quickcontrols subproject provides and uses a series of QDoc macros,
styleproperty/stylemethod/stylemethod2, that are used to provide a
stylized version of certain documentation element in the output
documentation.
Those macros takes a series of arguments and expand to certain styling
structures that are output format specific.
One of the arguments for each macro, is an identifier that is used in
the expanded structure.
As the macros are format specific, QDoc expands them into "raw" output
for each format, without further processing.
When doing so, the identifier that is provided as an argument, while it
expands to a link-able reference in the format-specific output, will not
be registered by QDoc, which uses an internal linking system, so that
linking to that reference with a QDoc command will fail.
To avoid the issue, each usage of the macro, as documented in the macro
definition, provides a "\target" command with the same identifier, that
QDoc expands to a link-able reference that is registered in the internal
linking system, allowing cross-referencing to work.
Nonetheless, since the same identifier is expanded both by the macro
usage and by the "\target" command adjacent to it, two equivalent
references will appear in the output.
In the DocBook format, on of the possible output format for
QDoc-generated documentation, duplicated references are a violation,
thus producing invalid output.
Since providing a link-able reference to the documented element still
requires the usage of a "\target" command and the expanded to reference
is not essential to the structure provided by the macros, the
styleproperty/stylemethod/stylemethod2 macros are now modified to not
require an identifier argument and avoid expanding to a named reference.
Each usage of the macro was modified to remove the now unused identifier
argument as a consequence of the removal.
Change-Id: Ibf093911ab07ff579d54dc85ed63dbb66bf0114a
Reviewed-by: Thibaut Cuvelier <cuvelier.thibaut@gmail.com>
Reviewed-by: Topi Reiniƶ <topi.reinio@qt.io>
Diffstat (limited to 'src/quickcontrols')
4 files changed, 24 insertions, 24 deletions
diff --git a/src/quickcontrols/doc/qtquickcontrols.qdocconf b/src/quickcontrols/doc/qtquickcontrols.qdocconf index 5699443ef2..12e9b9215f 100644 --- a/src/quickcontrols/doc/qtquickcontrols.qdocconf +++ b/src/quickcontrols/doc/qtquickcontrols.qdocconf @@ -68,34 +68,34 @@ tagfile = qtquickcontrols.tags macro.styleimport.HTML = "<table class=\"alignedsummary\"><tbody><tr><td class=\"memItemLeft rightAlign topAlign\"> Import Statement:</td><td class=\"memItemRight bottomAlign\"> import \1</td></tr><tr><td class=\"memItemLeft rightAlign topAlign\"> Since:</td><td class=\"memItemRight bottomAlign\"> \2</td></tr></tbody></table>" macro.styleimport.DocBook = "<db:variablelist><db:varlistentry><db:term>Import Statement</db:term><db:listitem><db:para>import \1</db:para></db:listitem></db:varlistentry><db:varlistentry><db:term>Since</db:term><db:listitem><db:para>\2</db:para></db:listitem></db:varlistentry></db:variablelist>" -# \styleproperty {propertyname} {enumeration} {html-target-id} +# \styleproperty {propertyname} {enumeration} # \target html-target-id # This property holds ... # (empty line) # \endstyleproperty -macro.styleproperty.HTML = "<div class=\"qmlproto\"><table class=\"qmlname\"><tbody><tr valign=\"top\" class=\"odd\" id=\"\3\"><td class=\"tblQmlPropNode\"><p><span class=\"name\">\1</span> : <span class=\"type\">\2</span></p></td></tr></tbody></table></div>" +macro.styleproperty.HTML = "<div class=\"qmlproto\"><table class=\"qmlname\"><tbody><tr valign=\"top\" class=\"odd\"><td class=\"tblQmlPropNode\"><p><span class=\"name\">\1</span> : <span class=\"type\">\2</span></p></td></tr></tbody></table></div>" macro.endstyleproperty.HTML = "<br/>" -macro.styleproperty.DocBook = "<db:section xml:id=\"\3\"><db:title>\1 : \2</db:title><db:fieldsynopsis><db:type>\2</db:type><db:varname>\1</db:varname></db:fieldsynopsis>" +macro.styleproperty.DocBook = "<db:section><db:title>\1 : \2</db:title><db:fieldsynopsis><db:type>\2</db:type><db:varname>\1</db:varname></db:fieldsynopsis>" macro.endstyleproperty.DocBook = "</db:section>" -# \stylemethod {returntype} {methodname} {argtype} {argname} {html-target-id} +# \stylemethod {returntype} {methodname} {argtype} {argname} # \target html-target-id # This property holds ... # (empty line) # \endstylemethod -macro.stylemethod.HTML = "<div class=\"qmlproto\"><table class=\"qmlname\"><tbody><tr valign=\"top\" class=\"odd\" id=\"\5\"><td class=\"tblQmlFuncNode\"><p><span class=\"type\">\1</span> <span class=\"name\">\2</span>(<span class="type">\3</span> <i>\4</i>)</p></td></tr></tbody></table></div>" +macro.stylemethod.HTML = "<div class=\"qmlproto\"><table class=\"qmlname\"><tbody><tr valign=\"top\" class=\"odd\"><td class=\"tblQmlFuncNode\"><p><span class=\"type\">\1</span> <span class=\"name\">\2</span>(<span class="type">\3</span> <i>\4</i>)</p></td></tr></tbody></table></div>" macro.endstylemethod.HTML = "<br/>" -macro.stylemethod.DocBook = "<db:section xml:id=\"\5\"><db:title>\1 \2(\3 <db:emphasis>\4</db:emphasis>)</db:title><db:methodsynopsis><db:type>\1</db:type><db:methodname>\2</db:methodname><db:methodparam><db:type>\3</db:type><db:parameter>\4</db:parameter></db:methodparam></db:methodsynopsis>" +macro.stylemethod.DocBook = "<db:section><db:title>\1 \2(\3 <db:emphasis>\4</db:emphasis>)</db:title><db:methodsynopsis><db:type>\1</db:type><db:methodname>\2</db:methodname><db:methodparam><db:type>\3</db:type><db:parameter>\4</db:parameter></db:methodparam></db:methodsynopsis>" macro.endstylemethod.DocBook = "</db:section>" -# \stylemethod2 {returntype} {methodname} {arg1type} {arg1name} {arg2type} {arg2name} {html-target-id} +# \stylemethod2 {returntype} {methodname} {arg1type} {arg1name} {arg2type} {arg2name} # \target html-target-id # This method returns ... # (empty line) # \endstylemethod2 -macro.stylemethod2.HTML = "<div class=\"qmlproto\"><table class=\"qmlname\"><tbody><tr valign=\"top\" class=\"odd\" id=\"\7\"><td class=\"tblQmlFuncNode\"><p><span class=\"type\">\1</span> <span class=\"name\">\2</span>(<span class="type">\3</span> <i>\4</i>, <span class="type">\5</span> <i>\6</i>)</p></td></tr></tbody></table></div>" +macro.stylemethod2.HTML = "<div class=\"qmlproto\"><table class=\"qmlname\"><tbody><tr valign=\"top\" class=\"odd\"><td class=\"tblQmlFuncNode\"><p><span class=\"type\">\1</span> <span class=\"name\">\2</span>(<span class="type">\3</span> <i>\4</i>, <span class="type">\5</span> <i>\6</i>)</p></td></tr></tbody></table></div>" macro.endstylemethod2.HTML = "<br/>" -macro.stylemethod2.DocBook = "<db:section xml:id=\"\7\"><db:title>\1 \2(\3 <db:emphasis>\4</db:emphasis>)</db:title><db:methodsynopsis><db:type>\1</db:type><db:methodname>\2</db:methodname><db:methodparam><db:type>\3</db:type><db:parameter>\4</db:parameter></db:methodparam><db:methodparam><db:type>\5</db:type><db:parameter>\6</db:parameter></db:methodparam></db:methodsynopsis>" +macro.stylemethod2.DocBook = "<db:section><db:title>\1 \2(\3 <db:emphasis>\4</db:emphasis>)</db:title><db:methodsynopsis><db:type>\1</db:type><db:methodname>\2</db:methodname><db:methodparam><db:type>\3</db:type><db:parameter>\4</db:parameter></db:methodparam><db:methodparam><db:type>\5</db:type><db:parameter>\6</db:parameter></db:methodparam></db:methodsynopsis>" macro.endstylemethod2.DocBook = "</db:section>" # \stylecolor {#6A00FF} {(default)} diff --git a/src/quickcontrols/doc/src/qtquickcontrols-imagine.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-imagine.qdoc index 337e06cd94..0f48f3f6a4 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-imagine.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-imagine.qdoc @@ -2493,7 +2493,7 @@ \section1 Attached Property Documentation - \styleproperty {Imagine.path} {string} {imagine-path-attached-prop} + \styleproperty {Imagine.path} {string} \target imagine-path-attached-prop This attached property holds the path to the image assets... diff --git a/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc index c361f5f1a7..4052337ef8 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc @@ -272,7 +272,7 @@ \section1 Attached Property Documentation - \styleproperty {Material.accent} {color} {material-accent-attached-prop} + \styleproperty {Material.accent} {color} \target material-accent-attached-prop This attached property holds the accent color of the theme. The property can be attached to any window or item. The value is propagated to children. @@ -296,7 +296,7 @@ \endstyleproperty - \styleproperty {Material.background} {color} {material-background-attached-prop} + \styleproperty {Material.background} {color} \target material-background-attached-prop This attached property holds the background color of the theme. The property can be attached to any window or item. The value is propagated to children. @@ -316,7 +316,7 @@ \endstyleproperty - \styleproperty {Material.elevation} {int} {material-elevation-attached-prop} + \styleproperty {Material.elevation} {int} \target material-elevation-attached-prop This attached property holds the elevation of the control. The higher the elevation, the deeper the shadow. The property can be attached to any control, @@ -339,7 +339,7 @@ \endstyleproperty - \styleproperty {Material.foreground} {color} {material-foreground-attached-prop} + \styleproperty {Material.foreground} {color} \target material-foreground-attached-prop This attached property holds the foreground color of the theme. The property can be attached to any window or item. The value is propagated to children. @@ -359,7 +359,7 @@ \endstyleproperty - \styleproperty {Material.primary} {color} {material-primary-attached-prop} + \styleproperty {Material.primary} {color} \target material-primary-attached-prop This attached property holds the primary color of the theme. The property can be attached to any window or item. The value is propagated to children. @@ -374,7 +374,7 @@ \endstyleproperty - \styleproperty {Material.theme} {enumeration} {material-theme-attached-prop} + \styleproperty {Material.theme} {enumeration} \target material-theme-attached-prop This attached property holds whether the theme is light or dark. The property can be attached to any window or item. The value is propagated to children. @@ -401,7 +401,7 @@ \endstyleproperty - \styleproperty {Material.roundedScale} {enumeration} {material-roundedScale-attached-prop} + \styleproperty {Material.roundedScale} {enumeration} \target material-roundedScale-attached-prop This attached property holds the radius of rounded corners used on the target control. The property can be attached to any window or item, but @@ -425,7 +425,7 @@ \endstyleproperty - \styleproperty {Material.containerStyle} {enumeration} {material-containerStyle-attached-prop} + \styleproperty {Material.containerStyle} {enumeration} \target material-containerStyle-attached-prop This attached property holds the style of the container used by the target control. The property can be attached to any window or item, but @@ -446,7 +446,7 @@ \section1 Attached Method Documentation - \stylemethod2 {color} {color} {enumeration} {predefined} {enumeration} {shade} {material-color-attached-method} + \stylemethod2 {color} {color} {enumeration} {predefined} {enumeration} {shade} \target material-color-attached-method This attached method returns the effective color value of the specified \l {pre-defined Material colors}{pre-defined Material color} combined with diff --git a/src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc index 3268b5b11a..eba367061f 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc @@ -146,7 +146,7 @@ \section1 Attached Property Documentation - \styleproperty {Universal.accent} {color} {universal-accent-attached-prop} + \styleproperty {Universal.accent} {color} \target universal-accent-attached-prop This attached property holds the accent color of the theme. The property can be attached to any window or item. The value is propagated to children. @@ -170,7 +170,7 @@ \endstyleproperty - \styleproperty {Universal.background} {color} {universal-background-attached-prop} + \styleproperty {Universal.background} {color} \target universal-background-attached-prop This attached property holds the background color of the theme. The property can be attached to any window or item. The value is propagated to children. @@ -190,7 +190,7 @@ \endstyleproperty - \styleproperty {Universal.foreground} {color} {universal-foreground-attached-prop} + \styleproperty {Universal.foreground} {color} \target universal-foreground-attached-prop This attached property holds the foreground color of the theme. The property can be attached to any window or item. The value is propagated to children. @@ -208,7 +208,7 @@ \image qtquickcontrols-universal-foreground.png \endtable - \styleproperty {Universal.theme} {enumeration} {universal-theme-attached-prop} + \styleproperty {Universal.theme} {enumeration} \target universal-theme-attached-prop This attached property holds whether the theme is light or dark. The property can be attached to any window or item. The value is propagated to children. @@ -237,7 +237,7 @@ \section1 Attached Method Documentation - \stylemethod {color} {color} {enumeration} {predefined} {color-attached-method} + \stylemethod {color} {color} {enumeration} {predefined} \target color-attached-method This attached method returns the effective color value of the specified \l {pre-defined Universal colors}{pre-defined Universal color}. |