docs/qapi-code-gen: change recommendations for cross-reference syntax
PATCH 1/1 docs/qapi-code-gen: change recommendations for cross-reference syntax
The blurb about @foo style references in qapi-code-gen.rst is out of date now, update it.
--- docs/devel/qapi-code-gen.rst | 11 ++++++++--- docs/devel/qapi-domain.rst | 1 + 2 files changed, 9 insertions(+), 3 deletions(-)
docs/devel/qapi-code-gen.rst +8 -3
@@ -943,9 +943,14 @@ The usual ****strong****, *\*emphasized\** and ````literal```` markup should be used. If you need a single literal ``*``, you will need to backslash-escape it. -Use ``@foo`` to reference a name in the schema. This is an rST -extension. It is rendered the same way as ````foo````, but carries -additional meaning. +Use ```foo``` to reference a name in the schema and generate a +cross-reference link. In the event that a cross-reference is ambiguous +and the manual compilation fails, `QAPI cross-reference roles +<QAPI-XREF>` can be used to narrow the cross-reference results. + +Use ``@foo`` to reference members, which do not currently have a +cross-reference target. This is an rST extension. It is rendered the +same way as ````foo````, but carries additional meaning. Example::
docs/devel/qapi-domain.rst +1 -0
@@ -375,6 +375,7 @@ Will allow you to add arbitrary field lists in QAPI directives:: :see also: Lorem ipsum, dolor sit amet ... +.. _QAPI-XREF: Cross-references ================
Signature · 1 line
2.50.1
Quoted 14 lines · John Snow
The blurb about @foo style references in
qapi-code-gen.rstis out of date now, update it.Signed-off-by John Snow <[email protected]>--- docs/devel/qapi-code-gen.rst | 11 ++++++++--- docs/devel/qapi-domain.rst | 1 + 2 files changed, 9 insertions(+), 3 deletions(-)docs/devel/qapi-code-gen.rst +0
-0
docs/devel/qapi-code-gen.rst The usual ****strong****, *\*emphasized\** and ````literal```` markup · line 949
Quoted 10 lines
docs/devel/qapi-code-gen.rst +4
-3@@ -943,9 +943,14 @@ The usual ****strong****, *\*emphasized\** and ````literal```` markup should be used. If you need a single literal ``*``, you will need to backslash-escape it. -Use ``@foo`` to reference a name in the schema. This is an rST -extension. It is rendered the same way as ````foo````, but carries -additional meaning. +Use ```foo``` to reference a name in the schema and generate a +cross-reference link. In the event that a cross-reference is ambiguous +and the manual compilation fails, `QAPI cross-reference roles +<QAPI-XREF>` can be used to narrow the cross-reference results.
Two spaces between sentences for consistency, please.
Scratch "manual".
The old text is about @foo, which could legitimately be used for any name. "A name in the schema" was fine. "Was", because we now want foo instead for certain names.
The new text is about foo, which can be used only for certain names:
modules and definitions. So the new text needs to be more precise than "a name in the schema".
The module feature is basically redundant and should not be used. Instead of referencing the beginning of audio.json with audio (shorthand for :qapi:mod:audio), you can (and should) reference its heading with Audio_. Plain reST instead of QAPI-specific extension (strike 1), section structure instead of module structure (strike 2). Let's not to advertize the module feature here.
This leaves definition names.
docs/devel/qapi-code-gen.rst The usual ****strong****, *\*emphasized\** and ````literal```` markup · line 953
Quoted 4 lines
docs/devel/qapi-code-gen.rst +4
-0+ +Use ``@foo`` to reference members, which do not currently have a +cross-reference target. This is an rST extension. It is rendered the +same way as ````foo````, but carries additional meaning.
I think the main point to make is that for members you need to use @foo. foo doesn't work there.
Here's my try:
Use ```foo``` to reference a definition in the schema. This generates a link to the definition. In the event that such a cross-reference is ambiguous, you can use QAPI cross-reference roles <QAPI-XREF> to disambiguate.
Use @foo to reference a member description within the current definition. This is an rST extension. It is currently rendered the same way as ````foo````, but carries additional meaning.
Quoted 15 lines
docs/devel/qapi-code-gen.rst +0
-0Example::docs/devel/qapi-domain.rst +1
-0@@ -375,6 +375,7 @@ Will allow you to add arbitrary field lists in QAPI directives:: :see also: Lorem ipsum, dolor sit amet ... +.. _QAPI-XREF: Cross-references ================
I took the liberty to post my version as "[PATCH 3/3] docs/devel/qapi-code-gen: Update cross-reference syntax" to speed up things. Hope you don't mind.