From 204c82e6b00ad362050d16013866b16c82dfcf5c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20Sch=C3=A4fer?= <jonas@zombofant.net>
Date: Wed, 24 Jul 2024 16:07:29 +0200
Subject: [PATCH] xso: add more doc comments throughout

---
 xso/src/lib.rs  | 19 +++++++++++++++++--
 xso/src/text.rs | 11 +++++++++++
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/xso/src/lib.rs b/xso/src/lib.rs
index a5b073da..73815aa9 100644
--- a/xso/src/lib.rs
+++ b/xso/src/lib.rs
@@ -164,24 +164,28 @@ pub trait FromXmlText: Sized {
 }
 
 impl FromXmlText for String {
+    /// Return the string unchanged.
     fn from_xml_text(data: String) -> Result<Self, self::error::Error> {
         Ok(data)
     }
 }
 
 impl<T: FromXmlText, B: ToOwned<Owned = T>> FromXmlText for Cow<'_, B> {
+    /// Return a [`Cow::Owned`] containing the parsed value.
     fn from_xml_text(data: String) -> Result<Self, self::error::Error> {
         Ok(Cow::Owned(T::from_xml_text(data)?))
     }
 }
 
 impl<T: FromXmlText> FromXmlText for Option<T> {
+    /// Return a [`Some`] containing the parsed value.
     fn from_xml_text(data: String) -> Result<Self, self::error::Error> {
         Ok(Some(T::from_xml_text(data)?))
     }
 }
 
 impl<T: FromXmlText> FromXmlText for Box<T> {
+    /// Return a [`Box`] containing the parsed value.
     fn from_xml_text(data: String) -> Result<Self, self::error::Error> {
         Ok(Box::new(T::from_xml_text(data)?))
     }
@@ -218,29 +222,40 @@ pub trait AsXmlText {
 }
 
 impl AsXmlText for String {
+    /// Return the borrowed string contents.
     fn as_xml_text(&self) -> Result<Cow<'_, str>, self::error::Error> {
         Ok(Cow::Borrowed(self.as_str()))
     }
 }
 
-impl AsXmlText for &str {
+impl AsXmlText for str {
+    /// Return the borrowed string contents.
     fn as_xml_text(&self) -> Result<Cow<'_, str>, self::error::Error> {
-        Ok(Cow::Borrowed(&**self))
+        Ok(Cow::Borrowed(&*self))
     }
 }
 
 impl<T: AsXmlText> AsXmlText for Box<T> {
+    /// Return the borrowed [`Box`] contents.
     fn as_xml_text(&self) -> Result<Cow<'_, str>, self::error::Error> {
         T::as_xml_text(self)
     }
 }
 
 impl<B: AsXmlText + ToOwned> AsXmlText for Cow<'_, B> {
+    /// Return the borrowed [`Cow`] contents.
     fn as_xml_text(&self) -> Result<Cow<'_, str>, self::error::Error> {
         B::as_xml_text(self.as_ref())
     }
 }
 
+impl<T: AsXmlText> AsXmlText for &T {
+    /// Delegate to the `AsXmlText` implementation on `T`.
+    fn as_xml_text(&self) -> Result<Cow<'_, str>, self::error::Error> {
+        T::as_xml_text(*self)
+    }
+}
+
 /// Specialized variant of [`AsXmlText`].
 ///
 /// Do **not** implement this unless you cannot implement [`AsXmlText`]:
diff --git a/xso/src/text.rs b/xso/src/text.rs
index 988a7d60..8e9bae2d 100644
--- a/xso/src/text.rs
+++ b/xso/src/text.rs
@@ -28,6 +28,7 @@ macro_rules! convert_via_fromstr_and_display {
                 #[cfg_attr(docsrs, doc(cfg(feature = $feature)))]
             )?
             impl FromXmlText for $t {
+                #[doc = concat!("Parse [`", stringify!($t), "`] from XML text via [`FromStr`][`core::str::FromStr`].")]
                 fn from_xml_text(s: String) -> Result<Self, Error> {
                     s.parse().map_err(Error::text_parse_error)
                 }
@@ -38,6 +39,7 @@ macro_rules! convert_via_fromstr_and_display {
                 #[cfg_attr(docsrs, doc(cfg(feature = $feature)))]
             )?
             impl AsXmlText for $t {
+                #[doc = concat!("Convert [`", stringify!($t), "`] to XML text via [`Display`][`core::fmt::Display`].\n\nThis implementation never fails.")]
                 fn as_xml_text(&self) -> Result<Cow<'_, str>, Error> {
                     Ok(Cow::Owned(self.to_string()))
                 }
@@ -48,6 +50,11 @@ macro_rules! convert_via_fromstr_and_display {
 
 /// This provides an implementation compliant with xsd::bool.
 impl FromXmlText for bool {
+    /// Parse a boolean from XML text.
+    ///
+    /// The values `"1"` and `"true"` are considered true. The values `"0"`
+    /// and `"false"` are considered `false`. Any other value is invalid and
+    /// will return an error.
     fn from_xml_text(s: String) -> Result<Self, Error> {
         match s.as_str() {
             "1" => "true",
@@ -61,6 +68,10 @@ impl FromXmlText for bool {
 
 /// This provides an implementation compliant with xsd::bool.
 impl AsXmlText for bool {
+    /// Convert a boolean to XML text.
+    ///
+    /// `true` is converted to `"true"` and `false` is converted to `"false"`.
+    /// This implementation never fails.
     fn as_xml_text(&self) -> Result<Cow<'_, str>, Error> {
         match self {
             true => Ok(Cow::Borrowed("true")),