From ad2c79cbe708399ad80fca19b9b4442297aa3698 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20Sch=C3=A4fer?= <jonas@zombofant.net>
Date: Sat, 10 Aug 2024 09:34:05 +0200
Subject: [PATCH] xso: document some specific trait implementations

---
 xso/src/asxml.rs   | 3 +++
 xso/src/fromxml.rs | 7 +++++++
 2 files changed, 10 insertions(+)

diff --git a/xso/src/asxml.rs b/xso/src/asxml.rs
index 3d15bd91..3b4e449e 100644
--- a/xso/src/asxml.rs
+++ b/xso/src/asxml.rs
@@ -38,6 +38,8 @@ impl<'x, T: Iterator<Item = Result<Item<'x>, Error>>> Iterator for OptionAsXml<T
     }
 }
 
+/// Emits the contents of `Some(.)` unchanged if present and nothing
+/// otherwise.
 impl<T: AsXml> AsXml for Option<T> {
     type ItemIter<'x> = OptionAsXml<T::ItemIter<'x>> where T: 'x;
 
@@ -60,6 +62,7 @@ impl<'x, T: Iterator<Item = Result<Item<'x>, Error>>> Iterator for BoxAsXml<T> {
     }
 }
 
+/// Emits the contents of `T` unchanged.
 impl<T: AsXml> AsXml for Box<T> {
     type ItemIter<'x> = BoxAsXml<T::ItemIter<'x>> where T: 'x;
 
diff --git a/xso/src/fromxml.rs b/xso/src/fromxml.rs
index 3c07f627..56d86c8f 100644
--- a/xso/src/fromxml.rs
+++ b/xso/src/fromxml.rs
@@ -26,6 +26,12 @@ impl<T: FromEventsBuilder> FromEventsBuilder for OptionBuilder<T> {
     }
 }
 
+/// Parsers `T` into `Some(.)`.
+///
+/// Note that this never generates `None`: The main use case is to allow
+/// external (i.e. without calling `from_events`) defaulting to `None` and
+/// for optional serialisation (the [`AsXml`][`crate::AsXml`] implementation
+/// on `Option<T>` emits nothing for `None`).
 impl<T: FromXml> FromXml for Option<T> {
     type Builder = OptionBuilder<T::Builder>;
 
@@ -48,6 +54,7 @@ impl<T: FromEventsBuilder> FromEventsBuilder for BoxBuilder<T> {
     }
 }
 
+/// Parsers `T` into a `Box`.
 impl<T: FromXml> FromXml for Box<T> {
     type Builder = BoxBuilder<T::Builder>;