Make Serializer and Deserializer pub and expose incomplete_enum mechanism

[jordens]

Summary

miniconf is a library we use to access (get/set over serial, mqtt, store in flash) settings on embedded devices. It is a serde-based hierarchical heterogeneous key-value access mechanism.
We'd like to generate a schema for the settings trees and found serde-reflection very useful for this (thanks!).

We implement the trace_value/trace_type functionality in Tracer using our intermediate miniconf::TreeSerialize/TreeDeserialize traits. See below for what that looks like.

For trace_value and trace_type_once we would like Serializer and Deserializer to be pub. Happy to split that out of this PR if it's uncontroversial.

For trace_type we also need a way to mark the top level enum in incomplete_enums before tracing again (see trace_type).

Test Plan

git clone https://github.com/quartiq/miniconf.git
cd miniconf
# note that miniconf is using this serde-reflection branch in miniconf/Cargo.toml
cargo run -p miniconf --example trace --all-features

Code: https://github.com/quartiq/miniconf/blob/898c4222cc83574c8db44dfe7f63e318736af6ef/miniconf/examples/trace.rs#L131-L173

/// Trace a leaf value
pub fn trace_value<T: TreeSerialize, K: Keys>(
    tracer: &mut Tracer,
    samples: &mut Samples,
    keys: K,
    value: &T,
) -> Result<(Format, Value), Error<serde_reflection::Error>> {
    value.serialize_by_key(keys, Serializer::new(tracer, samples))
}

/// Trace a leaf type once
pub fn trace_type_once<'de, T: TreeDeserialize<'de>, K: Keys>(
    tracer: &mut Tracer,
    samples: &'de Samples,
    keys: K,
) -> Result<Format, Error<serde_reflection::Error>> {
    let mut format = Format::unknown();
    T::probe_by_key(keys, Deserializer::new(tracer, samples, &mut format))?;
    format.reduce();
    Ok(format)
}

/// Trace a leaf type until complete
pub fn trace_type<'de, T: TreeDeserialize<'de>, K: Keys + Clone>(
    tracer: &mut Tracer,
    samples: &'de Samples,
    keys: K,
) -> Result<Format, Error<serde_reflection::Error>> {
    loop {
        let format = trace_type_once::<T, _>(tracer, samples, keys.clone())?;
        if let Format::TypeName(name) = &format {
            if let Some(progress) = tracer.pend_enum(name) {
                debug_assert!(
                    !matches!(progress, EnumProgress::Pending),
                    "failed to make progress tracing enum {name}"
                );
                // Restart the analysis to find more variants.
                continue;
            }
        }
        return Ok(format);
    }
}

[ma2bd]

Interesting. We may want to mark the newly public function(s) as #[doc(hidden)].

[jordens]

I think I found a decent way to keep up the invariant that only if incomplete_enums is empty, a complete registry can be returned and I left out the doc hiding. AFAICT it would not have made a difference w.r.t. semver rules anyway.
Let me know if you still prefer to hide the new API.