Re: [PATCH] docs/qapi-code-gen: change recommendations for cross-reference syntax

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> The blurb about @foo style references in qapi-code-gen.rst is out of
> date now, update it.
>
> Signed-off-by: John Snow <jsnow@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 dfdbeac5a5a..51993a6eb0c 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 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.

> +
> +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.

>  
>  Example::
>  
> diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst
> index b71890f6609..8d9fc866bc3 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-XREF:
>  
>  Cross-references
>  ================