xso: deprecate try_from_element

It is not necessary anymore, because we switched from `IntoXml` to
`AsXml`, allowing `transform` to work with a reference instead of
consuming its input.

Before that, `try_from_element` was the only way to fallibly attempt to
parse something from `Element` without having to clone the entire DOM.

xso/ChangeLog

@@ -61,6 +61,7 @@ Version NEXT:
       - Update rxml dependency to 0.13.
       - xso now rejects conflicting `#[xml(attribute)]` (and `#[xml(lang)]`)
         specifications at compile time.
+      - Deprecate `try_from_element` in favour of `transform`.
 
 Version 0.1.2:
 2024-07-26 Jonas Schäfer <jonas@zombofant.net>

xso/src/error.rs

@@ -52,9 +52,9 @@ pub enum Error {
 
     /// An element header did not match an expected element.
     ///
-    /// This is only rarely generated: most of the time, a mismatch of element
-    /// types is reported as either an unexpected or a missing child element,
-    /// errors which are generally more specific.
+    /// This error condition is only generated when the top-level element
+    /// passed to [`transform`][`crate::transform`] or similar does not match
+    /// the type.
     TypeMismatch,
 }
 

xso/src/lib.rs

@@ -510,10 +510,15 @@ pub fn transform<T: FromXml, F: AsXml>(from: &F) -> Result<T, self::error::Error
 /// function will return the element unharmed if its element header does not
 /// match the expectations of `T`.
 #[cfg(feature = "minidom")]
+#[deprecated(
+    since = "0.1.3",
+    note = "obsolete since the transition to AsXml, which works by reference; use xso::transform instead."
+)]
 pub fn try_from_element<T: FromXml>(
     from: minidom::Element,
 ) -> Result<T, self::error::FromElementError> {
     let mut languages = rxml::xml_lang::XmlLangStack::new();
+    #[allow(deprecated)]
     let (qname, attrs) = minidom_compat::make_start_ev_parts(&from)?;
 
     languages.push_from_attrs(&attrs);

xso/src/minidom_compat.rs

@@ -61,6 +61,12 @@ enum IntoEventsInner {
 // NOTE to developers: The limitations are not fully trivial to overcome:
 // the attributes use a BTreeMap internally, which does not offer a `drain`
 // iterator.
+#[deprecated(
+    since = "0.1.3",
+    note = "obsolete since the transition to AsXml. no replacement."
+)]
+// NOTE: instead of deleting this, make it non-pub to be able to continue to
+// use it in IntoEventsInner.
 pub fn make_start_ev_parts(el: &Element) -> Result<(rxml::QName, AttrMap), Error> {
     let name = NcName::try_from(el.name())?;
     let namespace = Namespace::from(el.ns());
@@ -95,6 +101,7 @@ impl IntoEventsInner {
     fn next(&mut self) -> Result<Option<Event>, Error> {
         match self {
             IntoEventsInner::Header(ref mut el) => {
+                #[allow(deprecated)]
                 let (qname, attrs) = make_start_ev_parts(el)?;
                 let event = Event::StartElement(EventMetrics::zero(), qname, attrs);