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 { Ok(data) } } impl> FromXmlText for Cow<'_, B> { + /// Return a [`Cow::Owned`] containing the parsed value. fn from_xml_text(data: String) -> Result { Ok(Cow::Owned(T::from_xml_text(data)?)) } } impl FromXmlText for Option { + /// Return a [`Some`] containing the parsed value. fn from_xml_text(data: String) -> Result { Ok(Some(T::from_xml_text(data)?)) } } impl FromXmlText for Box { + /// Return a [`Box`] containing the parsed value. fn from_xml_text(data: String) -> Result { 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, 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, self::error::Error> { - Ok(Cow::Borrowed(&**self)) + Ok(Cow::Borrowed(&*self)) } } impl AsXmlText for Box { + /// Return the borrowed [`Box`] contents. fn as_xml_text(&self) -> Result, self::error::Error> { T::as_xml_text(self) } } impl AsXmlText for Cow<'_, B> { + /// Return the borrowed [`Cow`] contents. fn as_xml_text(&self) -> Result, self::error::Error> { B::as_xml_text(self.as_ref()) } } +impl AsXmlText for &T { + /// Delegate to the `AsXmlText` implementation on `T`. + fn as_xml_text(&self) -> Result, 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 { 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, 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 { 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, Error> { match self { true => Ok(Cow::Borrowed("true")),