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? > > > 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? > Yes, see the disambiguation patch for qapi-domain.rst for proof. Roll it back and see what happens! > > > 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:"? > Haha! Yes, I suppose I did. > > > 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 <js...@redhat.com> > >
