xso: add more doc comments throughout

Jonas Schäfer created 2 years ago

Change summary

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

Detailed changes

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`]:

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")),