Merge pull request #121 from quartiq/rj/from-into-docs

add from/into docs

README.md

@@ -84,7 +84,7 @@ settings.set("option_defer", b"13").unwrap_err();
 settings.option_defer = Some(0);
 settings.set("option_defer", b"13")?;
 settings.set("option_miniconf/a", b"14").unwrap_err();
-*settings.option_miniconf = Some(Inner::default());
+settings.option_miniconf = Some(Inner::default()).into();
 settings.set("option_miniconf/a", b"14")?;
 
 // Serializing an element by path

src/array.rs

@@ -1,32 +1,40 @@
-//! Array support
-//!
-//! # Design
-//! Miniconf supports homogeneous arrays of items contained in structures using two forms. For the
-//! [`Array`], each item of the array is accessed as a `Miniconf` tree.
-//!
-//! For standard arrays of [T; N] form, each item of the array is accessed as one atomic
-//! value (i.e. a single Miniconf item).
-//!
-//! The type you should use depends on what data is contained in your array. If your array contains
-//! `Miniconf` items, you can (and often want to) use [`Array`]. However, if each element in your list is
-//! individually configurable as a single value (e.g. a list of u32), then you must use a
-//! standard [T; N] array.
 use super::{Error, IterError, Metadata, Miniconf, Peekable};
 
 use core::fmt::Write;
-
-/// An array that exposes each element through their [`Miniconf`](trait.Miniconf.html) implementation.
+use core::ops::{Deref, DerefMut};
+
+/// An array that exposes each element through their [`Miniconf`] implementation.
+///
+/// # Design
+///
+/// Miniconf supports homogeneous arrays of items contained in structures using two forms. For the
+/// [`miniconf::Array`](Array), each item of the array is accessed as a [`Miniconf`] tree.
+///
+/// For standard arrays of [`[T; N]`](array) form, by default the entire array is accessed as one atomic
+/// value. By adding the `#[miniconf(defer)]` attribute, each index of the array is is instead accessed as
+/// one atomic value (i.e. a single Miniconf item).
+///
+/// The type you should use depends on what data is contained in your array. If your array contains
+/// `Miniconf` items, you can (and often want to) use [`Array`] and the `#[miniconf(defer)]` attribute.
+/// However, if each element in your list is individually configurable as a single value (e.g. a list
+/// of `u32`), then you must use a standard [`[T; N]`](array) array but you may optionally
+/// `#[miniconf(defer)]` access to individual indices.
+///
+/// # Construction
+///
+/// An `Array` can be constructed using [`From<[T; N]>`](From)/[`Into<miniconf::Array>`]
+/// and the contained value can be accessed through [`Deref`]/[`DerefMut`].
 #[derive(Clone, Copy, PartialEq, Eq, Debug, PartialOrd, Ord, Hash)]
 pub struct Array<T, const N: usize>([T; N]);
 
-impl<T, const N: usize> core::ops::Deref for Array<T, N> {
+impl<T, const N: usize> Deref for Array<T, N> {
     type Target = [T; N];
 
     fn deref(&self) -> &Self::Target {
         &self.0
     }
 }
-impl<T, const N: usize> core::ops::DerefMut for Array<T, N> {
+impl<T, const N: usize> DerefMut for Array<T, N> {
     fn deref_mut(&mut self) -> &mut Self::Target {
         &mut self.0
     }

src/option.rs

@@ -1,24 +1,34 @@
-//! Option Support
-//!
-//! # Design
-//!
-//! Miniconf supports optional values in two forms. The first for is the [`Option`] type. If the
-//! `Option` is `None`, the part of the namespace does not exist at run-time.
-//! It will not be iterated over and cannot be `get()` or `set()` using the Miniconf API.
-//!
-//! This is intended as a mechanism to provide run-time construction of the namespace. In some
-//! cases, run-time detection may indicate that some component is not present. In this case,
-//! namespaces will not be exposed for it.
-//!
-//!
-//! # Standard Options
-//!
-//! Miniconf also allows for the normal usage of Rust `Option` types. In this case, the `Option`
-//! can be used to atomically access the nullable content within.
-
 use super::{Error, IterError, Metadata, Miniconf, Peekable};
-
-/// An `Option` that exposes its value through their [`Miniconf`](trait.Miniconf.html) implementation.
+use core::ops::{Deref, DerefMut};
+
+/// An `Option` that exposes its value through their [`Miniconf`] implementation.
+///
+/// # Design
+///
+/// Miniconf supports optional values in two forms.
+///
+/// In both forms, the `Option` may be marked with `#[miniconf(defer)]`
+/// and be `None` at run-time. This makes the corresponding part of the namespace inaccessible
+/// at run-time. It will still be iterated over by [`Miniconf::iter_paths()`] but cannot be
+/// `get()` or `set()` using the [`Miniconf`] API.
+///
+/// This is intended as a mechanism to provide run-time construction of the namespace. In some
+/// cases, run-time detection may indicate that some component is not present. In this case,
+/// namespaces will not be exposed for it.
+///
+/// The first form is the [`miniconf::Option`](Option) type which optionally exposes its
+/// interior `Miniconf` value as a sub-tree. An [`miniconf::Option`](Option) should usually be
+/// `#[miniconf(defer)]`.
+///
+/// Miniconf also allows for the normal usage of Rust [`core::option::Option`] types. In this case,
+/// the `Option` can be used to atomically access the content within. If marked with `#[miniconf(defer)]`
+/// and `None` at runtime, it is inaccessible through `Miniconf`. Otherwise, JSON `null` corresponds to
+/// `None` as usual.
+///
+/// # Construction
+///
+/// An `miniconf::Option` can be constructed using [`From<core::option::Option>`]/[`Into<miniconf::Option>`]
+/// and the contained value can be accessed through [`Deref`]/[`DerefMut`].
 #[derive(
     Clone,
     Copy,
@@ -34,14 +44,14 @@ use super::{Error, IterError, Metadata, Miniconf, Peekable};
 )]
 pub struct Option<T>(core::option::Option<T>);
 
-impl<T> core::ops::Deref for Option<T> {
+impl<T> Deref for Option<T> {
     type Target = core::option::Option<T>;
 
     fn deref(&self) -> &Self::Target {
         &self.0
     }
 }
-impl<T> core::ops::DerefMut for Option<T> {
+impl<T> DerefMut for Option<T> {
     fn deref_mut(&mut self) -> &mut Self::Target {
         &mut self.0
     }