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

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Thu, Mar 13, 2025 at 2:47 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> 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?
>>
>
> do wha?

Sorry, I went into the curve too fast.

The stuff under "References now work like this" confuses me.  I guess it
describes a series of lookups to try one after the other.

I understand a cross-reference consists of namespace (optional), module
(optional), name, and role.

Let's assume role is "any" for simplicity's sake.

Regarding "1. If the explicit ...":

    What is a reference's "explicit reference target"?  Examples might
    help me understand.

    What is "recorded in the domain's object registry"?

    Can you show me a reference where this lookup succeeds?

Regarding "2. If contextual information ...":

    I guess "contextual information" is the context established by
    qapi:namespace and qapi:module directives, i.e. the current
    namespace and module, if any.

    If the cross reference lacks a namespace, we substitute the current
    namespace.  Same for module.

    We then use that "to find a direct match to the implied target
    name".  Sounds greek to me.  Example(s) might help.

Regarding "3. If both prior lookups fail ...":

    I guess we get here when namespace or module are absent, and
    substituting the current namespace or module doesn't resolve.  We
    then substitute a wildcard, so to speak, i.e. look in all namespaces
    / modules, and succeed if we find exactly one resolution.  Fair?

[...]