John Snow <js...@redhat.com> writes:
> On Thu, Mar 13, 2025 at 2:47 AM Markus Armbruster <arm...@redhat.com> wrote:
>
>> John Snow <js...@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?
[...]
