clean up documentation of target attribute

base_classes/NXdata.nxdl.xml

@@ -311,16 +311,25 @@
 	</attribute>
 	<attribute name="target">
         <doc>
-			Points to the path of a group defining the data to which the `DATA` group refers.
+		    Points to the path of a group defining the data to which this NXdata group refers.
 
-			This attribute indicates the origin of the data, thereby providing an association to
-			further metadata that define the physical quantity that the data represents.
+			This attribute indicates the **origin** of the ``NXdata`` group, thereby providing an association to
+			further metadata that define the physical quantity that the data represents. It can be used to
+			provide human-readable information about where this ``NXdata`` group comes from.
+
+			In case the ``NXdata`` group is a resolvable link to another group, the ``@target`` attribute should be the target of the link.
+			In case of links to other ``NXdata`` groups that are not necessary resolvable (i.e., for hard links to different files) or for simple copies
+			of ``NXdata`` groups, the ``@target`` attribute points to the path of the original data source.
+
+			The ``target`` attribute of ``NXdata`` allows referencing of whole ``NXdata`` groups. If only a specific axis or data field
+			is referenced from somewhere else, the ``target`` attribute of the respective field (i.e., of ``AXISNAME`` or ``DATA``)
+			should be used.
 
 			Example:
-			    If the data corresponds to a readout of a detector, ``@target`` points
-				to that detectors data:
+			    If the root-level ``NXdata`` corresponds to a readout of a detector, ``@target`` points
+				to that the ``NXdata`` group of the `NXdetector` group describing this detector:
 
-				  @target: '/entry/instrument/detector/data' for a detector
+				  @target: '/entry/instrument/detector/data'
         </doc>
     </attribute>
 	<attribute name="AXISNAME_indices" type="NX_INT" nameType="partial">
@@ -392,16 +401,20 @@
 				This attribute indicates the origin of the axis, thereby providing an association to
 				further metadata that define the physical quantity that the ``AXISNAME`` represents.
 
+				The usage of the ``target`` attribute is similar to that of the :ref:`target &lt;/NXdata@target-attribute&gt;` attribute
+				of the ``NXdata`` group. However, the attribute here is to be used if only a specific axis (instead of the whole group)
+				is referenced from somewhere else.
+
 				Examples:
 				    If a calibration has been performed, ``@target`` points to the result of
 					that calibration:
 
-					  @target: '/entry/process/calibration/calibrated_axis'
+					  @target: '/entry/calibration/calibrated_axis'
 
 				    If the axis corresponds to a coordinate of a detector, ``@target`` points
 					to that detector axis:
 
-					  @target: '/entry/instrument/detector/axis/some_axis' for a 2D detector
+					  @target: '/entry/instrument/detector/axis/some_axis' for a detector
 
 					If the axis is a scanned motor, ``@target`` points to the transformation
 					describing the respective motion, e.g.:
@@ -459,11 +472,17 @@
 				This attribute indicates the origin of the data, thereby providing an association to
 				further metadata that define the physical quantity that the ``DATA`` represents.
 
+				The usage of the ``target`` attribute is similar to that of the :ref:`target &lt;/NXdata@target-attribute&gt;` attribute
+				of the ``NXdata`` group. However, the attribute here is to be used if only a specific data field (instead of the whole group)
+				is referenced from somewhere else.
+
 				Example:
-				    If the data corresponds to a readout of a detector, ``@target`` points
-					to that detectors data:
+				    If the ``intensity`` field in an ``NXdata`` group corresponds to the measured readout
+					of a detector, the ``@target`` attribute of the ``intensity`` field points to
+
+					  @target: '/entry/instrument/detector/data',
 
-					  @target: '/entry/instrument/detector/data' for a 2D detector
+					where ``data`` is a field in the ``NXdetector`` group.
             </doc>
         </attribute>
 	</field>