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? > 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 <js...@redhat.com>
