refine language around open enumerations

dev_tools/docs/nxdl.py

@@ -514,7 +514,7 @@ def _print_enumeration(self, indent, ns, parent):
 
         if parent.attrib.get("open", "false") == "true":
             self._print(
-                f"{indent}Any of these values or a custom value:",
+                f"{indent}Any of these values or a custom value (if you use a custom value, also set @custom=True):",
                 end="",
             )
         else:

nxdl.xsd

@@ -1232,12 +1232,7 @@ https://stackoverflow.com/a/48980995/1046449 -->
 
 				(This data type is used internally in the NXDL schema 
 				to define elements and attributes to be used by users in NXDL specifications.)
-
-				Enumerations can be closed or open. A closed enumeration is one where the list of
-				values are the only ones allowed for a specification. An open enumeration is one 
-				where the list of values is incomplete and additional values other than those listed
-				are allowed.
-
+
 				::
 
 					<field name="mode">
@@ -1249,6 +1244,17 @@ https://stackoverflow.com/a/48980995/1046449 -->
 						</enumeration>
 					</field>
 
+				Enumerations can be closed or open. A closed enumeration is one where the list of
+				values are the only ones allowed for a specification. An open enumeration is one 
+				where the list of values is incomplete and additional values other than those listed
+				are allowed. Open enumerations should be used sparingly as the designer of the enumeration
+				should try to find all possible values for a given field/attribute.
+
+				In case an open enumeration is used, the data provider should, 
+
+				* for fields, set the attribute ``@custom=True``.
+				* for attributes, set an additional attribute ``@my_attribute_custom=True``, where 
+				  ``my_attribute`` is the name of the attribute with the open enumeration.
 			</xs:documentation>
 		</xs:annotation>
 		<xs:sequence>