diff options
Diffstat (limited to 'docs/devel/qapi-domain.rst')
| -rw-r--r-- | docs/devel/qapi-domain.rst | 34 |
1 files changed, 30 insertions, 4 deletions
diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index 73e13ab45c..4705ba255e 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -400,11 +400,10 @@ Namespaces Mimicking the `Python domain target specification syntax <https://www.sphinx-doc.org/en/master/usage/domains/python.html#target-specification>`_, QAPI allows you to specify the fully qualified path for a data -type. QAPI enforces globally unique names, so it's unlikely you'll need -this specific feature, but it may be extended in the near future to -allow referencing identically named commands and data types from -different utilities; i.e. QEMU Storage Daemon vs QMP. +type. +* A namespace can be explicitly provided; + e.g. ``:qapi:type:`QMP:BitmapSyncMode`` * A module can be explicitly provided; ``:qapi:type:`block-core.BitmapSyncMode``` will render to: :qapi:type:`block-core.BitmapSyncMode` @@ -413,6 +412,28 @@ different utilities; i.e. QEMU Storage Daemon vs QMP. will render to: :qapi:type:`~block-core.BitmapSyncMode` +Target resolution +----------------- + +Any cross-reference to a QAPI type, whether using the ```any``` style of +reference or the more explicit ```:qapi:any:`target``` syntax, allows +for the presence or absence of either the namespace or module +information. + +When absent, their value will be inferred from context by the presence +of any ``qapi:namespace`` or ``qapi:module`` directives preceding the +cross-reference. + +If no results are found when using the inferred values, other +namespaces/modules will be searched as a last resort; but any explicitly +provided values must always match in order to succeed. + +This allows for efficient cross-referencing with a minimum of syntax in +the large majority of cases, but additional context or namespace markup +may be required outside of the QAPI reference documents when linking to +items that share a name across multiple documented QAPI schema. + + Custom link text ---------------- @@ -492,6 +513,11 @@ directives are associated with the most recent namespace. This affects the definition's "fully qualified name", allowing two different namespaces to create an otherwise identically named definition. +This directive also influences how reference resolution works for any +references that do not explicity specify a namespace, so this directive +can be used to nudge references into preferring targets from within that +namespace. + Example:: .. qapi:namespace:: QMP |