diff --git a/contributed_definitions/NXiv_temp.nxdl.xml b/contributed_definitions/NXiv_temp.nxdl.xml index 87ec89d0d1..489841bf1b 100644 --- a/contributed_definitions/NXiv_temp.nxdl.xml +++ b/contributed_definitions/NXiv_temp.nxdl.xml @@ -90,9 +90,9 @@ There should also be a field with an array of rank equal to the number of different temperature setpoints and each child's dimension equal to the number of voltage setpoints. - - - + + + diff --git a/dev_tools/docs/nxdl.py b/dev_tools/docs/nxdl.py index bd8e98ccf2..7c1e19ff6b 100644 --- a/dev_tools/docs/nxdl.py +++ b/dev_tools/docs/nxdl.py @@ -608,6 +608,12 @@ def _print_attribute(self, ns, kind, node, optional, indent, parent_path): self._print_if_deprecated(ns, node, indent + self._INDENTATION_UNIT) self._print_doc_enum(indent, ns, node) + def _get_extends_text(self, node): + extends = node.get("extends", None) + if extends: + return f"(:ref:`{extends.split("/")[-1]} <{extends}-field>`) " + return "" + def _print_if_deprecated(self, ns, node, indent): deprecated = node.get("deprecated", None) if deprecated is not None: @@ -635,6 +641,7 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path): dims = self._analyze_dimensions(ns, node) optional_text = self._get_required_or_optional_text(node) + extends_test = self._get_extends_text(node) self._print( f"{indent}{self._hyperlink_target(parent_path, name, 'field')}" ) @@ -642,13 +649,14 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path): self._print( f"{indent}{formatted_name}: " f"{optional_text}" + f"{extends_test}" f"{self._format_type(node)}" f"{dims}" f"{self._format_units(node)}" f" {self.get_first_parent_ref(f'{parent_path}/{name}', 'field')}" "\n" ) - + self._print_extends_text(ns, node, indent + self._INDENTATION_UNIT) self._print_if_deprecated(ns, node, indent + self._INDENTATION_UNIT) self._print_doc_enum(indent, ns, node) diff --git a/nxdl.xsd b/nxdl.xsd index c9f2744739..5615945dc2 100755 --- a/nxdl.xsd +++ b/nxdl.xsd @@ -963,6 +963,44 @@ https://stackoverflow.com/a/48980995/1046449 --> + + + + The ``extends`` attribute allows to specify which field + in the inheritance hierarchy this field is derived from. + + This attribute is to be used in cases where there is an ambiguity + in the inheritance. At the moment, this is only the case for the + ``AXISNAME`` and ``DATA`` fields in ``NXdata``, which are both of + type ``NX_NUMBER``. Thus, when specializing ``NXdata`` in an application + definition, the ``extends`` attribute allows to specify whether a field + in the specialized ``NXdata`` is an ``AXISNAME`` and ``DATA``. + + For example, consider the following NXDL snippet:: + + <definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="application" name="NXexample" extends="NXobject" type="group" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"> + <doc>Example application definition.</doc> + <group type="NXentry"> + <group type="NXdata"> + <doc> + This NXdata contains multiple fields. ``temperature`` and ``voltage``specialize ``AXISNAME``, whereas ``current`` specializes ``DATA``. + </doc> + <field name="temperature" type="NX_NUMBER" extends="/NXdata/AXISNAME"/> + <field name="voltage" type="NX_NUMBER" extends="/NXdata/AXISNAME"/> + <field name="current" type="NX_NUMBER" extends="/NXdata/DATA"/> + </group> + </group> + </definition> + + Here, the ``extends`` attribute is used to specify that the ``temperature`` and ``voltage`` fields are specializations + of the ``AXISNAME`` field, whereas the ``current`` field is a specialization of the ``DATA`` field. + + Note that the ``extends`` keyword shall only be used in cases where there is an ambiguity in the inheritance, such as + the example above. The ``extends`` attribute must not be used when such ambiguity does not exist. Especially, it is + not alllowed to specify the ``extends`` attribute for fields that are not part of the inheritance hierarchy. + + +