On Thu, Jul 31, 2025 at 1:40 AM Markus Armbruster <arm...@redhat.com> wrote: > > The new QAPI code generator creates a cross-reference target for each > definition documentation. Enabled for the QEMU QMP Reference manual > in commit a377f39f38f, and for the QEMU Storage Daemon QMP Reference > Manual and the QEMU Guest Agent Protocol Reference in commit > a6af5443440. We've put these targets to use since, but neglected to > update doc comment markup documentation. Do that now. > > Co-developed-by: John Snow <js...@redhat.com>
No need for this in my opinion, the SOB suffices to say the same thing in my book. I don't insist you remove it, just seems ... oddly pretentious to say I "co-developed" a single paragraph of text ;) > Signed-off-by: John Snow <js...@redhat.com> > Signed-off-by: Markus Armbruster <arm...@redhat.com> Reviewed-by: John Snow <js...@redhat.com> > --- > docs/devel/qapi-code-gen.rst | 11 ++++++++--- > docs/devel/qapi-domain.rst | 1 + > 2 files changed, 9 insertions(+), 3 deletions(-) > > diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst > index 2cd51729c3..d97602f464 100644 > --- a/docs/devel/qapi-code-gen.rst > +++ b/docs/devel/qapi-code-gen.rst > @@ -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 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-domain-cross-references>` 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. > > Example:: > > diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst > index fe540d1e40..1924f12d42 100644 > --- a/docs/devel/qapi-domain.rst > +++ b/docs/devel/qapi-domain.rst > @@ -375,6 +375,7 @@ Will allow you to add arbitrary field lists in QAPI > directives:: > > :see also: Lorem ipsum, dolor sit amet ... > > +.. _QAPI-domain-cross-references: > > Cross-references > ================ > -- > 2.49.0 >
