From fa039c588beae9804ff66d2ecd17287fabf152ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Sch=C3=A4fer?= Date: Mon, 16 Dec 2024 19:04:23 +0100 Subject: [PATCH] xso: improve wording in AsXmlText and AsOptionalXmlText --- xso/src/lib.rs | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/xso/src/lib.rs b/xso/src/lib.rs index 79c7d1c6a87bbd3bb5a9319f736afa34717fe62f..a96ba8546a3363c2dc638281e528d7968343306e 100644 --- a/xso/src/lib.rs +++ b/xso/src/lib.rs @@ -198,6 +198,17 @@ impl FromXmlText for Box { /// 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 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.