xso: improve wording in AsXmlText and AsOptionalXmlText

xso/src/lib.rs

@@ -198,6 +198,17 @@ impl<T: FromXmlText> FromXmlText for Box<T> {
 
 /// Trait to convert a value to an XML text string.
 ///
+/// Implementing this trait for a type allows it to be used both for XML
+/// character data within elements and for XML attributes. For XML attributes,
+/// the behaviour is defined by [`AsXmlText::as_optional_xml_text`], while
+/// XML element text content uses [`AsXmlText::as_xml_text`]. Implementing
+/// [`AsXmlText`] automatically provides an implementation of
+/// [`AsOptionalXmlText`].
+///
+/// If your type should only be used in XML attributes and has no correct
+/// serialisation in XML text, you should *only* implement
+/// [`AsOptionalXmlText`] and omit the [`AsXmlText`] implementation.
+///
 /// This trait is implemented for many standard library types implementing
 /// [`core::fmt::Display`]. In addition, the following feature flags can enable
 /// more implementations:
@@ -263,13 +274,15 @@ impl<T: AsXmlText> AsXmlText for &T {
 
 /// Specialized variant of [`AsXmlText`].
 ///
-/// Do **not** implement this unless you cannot implement [`AsXmlText`]:
-/// implementing [`AsXmlText`] is more versatile and an
-/// [`AsOptionalXmlText`] implementation is automatically provided.
+/// Normally, it should not be necessary to implement this trait as it is
+/// automatically implemented for all types implementing [`AsXmlText`].
+/// However, if your type can only be serialised as an XML attribute (for
+/// example because an absent value has a particular meaning), it is correct
+/// to implement [`AsOptionalXmlText`] **instead of** [`AsXmlText`].
 ///
-/// If you need to customize the behaviour of the [`AsOptionalXmlText`]
-/// blanket implementation, implement a custom
-/// [`AsXmlText::as_optional_xml_text`] instead.
+/// If your type can be serialised as both (text and attribute) but needs
+/// special handling in attributes, implement [`AsXmlText`] but provide a
+/// custom implementation of [`AsXmlText::as_optional_xml_text`].
 pub trait AsOptionalXmlText {
     /// Convert the value to an XML string in a context where an absent value
     /// can be represented.