Re: [PATCH 07/11] docs/qapi_domain: add namespace support to cross-references

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> This patch does three things:
>
> 1. Record the current namespace context in pending_xrefs so it can be
>    used for link resolution later,
> 2. Pass that recorded namespace context to find_obj() when resolving a
>    reference, and
> 3. Wildly and completely rewrite find_obj().
>
> cross-reference support is expanded to tolerate the presence or absence
> of either namespace or module, and to cope with the presence or absence
> of contextual information for either.
>
> References now work like this:
>
> 1. If the explicit reference target is recorded in the domain's object
>    registry, we link to that target and stop looking. We do this lookup
>    regardless of how fully qualified the target is, which allows direct
>    references to modules (which don't have a module component to their
>    names) or direct references to definitions that may or may not belong
>    to a namespace or module.
>
> 2. If contextual information is available from qapi:namespace or
>    qapi:module directives, try using those components to find a direct
>    match to the implied target name.
>
> 3. If both prior lookups fail, generate a series of regular expressions
>    looking for wildcard matches in order from most to least
>    specific. Any explicitly provided components (namespace, module)
>    *must* match exactly, but both contextual and entirely omitted
>    components are allowed to differ from the search result. Note that if
>    more than one result is found, Sphinx will emit a warning (a build
>    error for QEMU) and list all of the candidate references.
>
> The practical upshot is that in the large majority of cases, namespace
> and module information is not required when creating simple `references`
> to definitions from within the same context -- even when identical
> definitions exist in other contexts.

Can you illustrate this this examples?

> Even when using simple `references` from elsewhere in the QEMU
> documentation manual, explicit namespace info is not required if there
> is only one definition by that name.

Fails safely: if we add a second definition, doc generation errors out.
Correct?

> Disambiguation *will* be required from outside of the QAPI documentation
> when referencing e.g. block-core definitions, which are shared between
> QEMU QMP and the QEMU Storage Daemon. In that case, there are two
> options:
>
> A: References can be made partially or fully explicit,
>    e.g. `QMP:block-dirty-bitmap-add` will link to the QEMU version of
>    the definition, while `QGA:block-dirty-bitmap-add` would link to the
>    QGA version.

Do you mean "QSD:"?

> B: If all of the references in a document are intended to go to the same
>    place, you can insert a "qapi:namespace:: QMP" directive to influence
>    the fuzzy-searching for later references.
>
> Signed-off-by: John Snow <jsnow@redhat.com>