Trait StructDoc

Source
pub trait StructDoc {
    // Required method
    fn document() -> Documentation;
}
Expand description

Types that can provide their own documentation at runtime.

It is provided for basic types and containers in the standard library. It should be possible to derive for most of the rest.

§Examples

use structdoc::StructDoc;

#[derive(StructDoc)]
struct Point {
    /// The horizontal coordinate.
    x: i32,

    /// The vertical coordinate.
    y: i32,
}

let documentation = format!("{}", Point::document());
let expected = r#"<root> (Struct):
  * Field x (Integer):
    | The horizontal coordinate.
  * Field y (Integer):
    | The vertical coordinate.
"#;

assert_eq!(expected, documentation);

§Deriving the trait

If the structdoc-derive feature is enabled (it is by default), it is possible to derive the trait on structs and enums. The text of documentation is extracted from the doc comments. Furthermore, it allows tweaking the implementation by attributes.

Because the primary aim of this crate is to provide user documentation for things fed to the application a lot of such things are handled by the serde crate, our derive can use both its own attributes and serde ones where it makes sense.

§Ignoring fields and variants

They can be ignored by placing either #[doc(hidden)], #[serde(skip)], #[serde(skip_deserialize)] or #[structdoc(skip)] attributes on them.

§Stubbing out implementations

If a field’s type doesn’t implement the trait or if recursing into it is not wanted (or maybe because the data structure is cyclic), it can be prefixed with the #[structdoc(leaf)] or #[structdoc(leag = "Type")] attribute. It’ll provide trivial implementation without any explanation and the provided type in parenthesis, if one is provided.

Alternatively, a function fn() -> Documentation can be plugged in using the #[structdoc(with = "path::to::the_fn")]. That can return an arbitrary implementation.

§Renaming things

The rename and rename_all attributes are available, both in serde and structdoc variants. They have the same meaning as withing serde.

§Flattening

The #[serde(flatten)] and #[structdoc(flatten)] flattens structures inline.

§Enum representations

The serde (and structdoc alternatives) of [tag representation] attributes are available.

Required Methods§

Source

fn document() -> Documentation

Returns the documentation for the type.

§Examples
use structdoc::StructDoc;

println!("Documentation: {}", Vec::<Option<String>>::document());

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types§

Source§

impl StructDoc for IpAddr

Source§

impl StructDoc for SocketAddr

Source§

impl StructDoc for bool

Source§

impl StructDoc for char

Source§

impl StructDoc for f32

Source§

impl StructDoc for f64

Source§

impl StructDoc for i8

Source§

impl StructDoc for i16

Source§

impl StructDoc for i32

Source§

impl StructDoc for i64

Source§

impl StructDoc for i128

Source§

impl StructDoc for isize

Source§

impl StructDoc for str

Source§

impl StructDoc for u8

Source§

impl StructDoc for u16

Source§

impl StructDoc for u32

Source§

impl StructDoc for u64

Source§

impl StructDoc for u128

Source§

impl StructDoc for ()

Source§

impl StructDoc for usize

Source§

impl StructDoc for CString

Source§

impl StructDoc for String

Source§

impl StructDoc for CStr

Source§

impl StructDoc for Ipv4Addr

Source§

impl StructDoc for Ipv6Addr

Source§

impl StructDoc for SocketAddrV4

Source§

impl StructDoc for SocketAddrV6

Source§

impl StructDoc for Duration

Source§

impl StructDoc for OsStr

Source§

impl StructDoc for OsString

Source§

impl StructDoc for Path

Source§

impl StructDoc for PathBuf

Source§

impl StructDoc for Instant

Source§

impl StructDoc for SystemTime

Source§

impl StructDoc for NonZeroU8

Source§

impl StructDoc for NonZeroU16

Source§

impl StructDoc for NonZeroU32

Source§

impl StructDoc for NonZeroU64

Source§

impl StructDoc for NonZeroU128

Source§

impl<K: StructDoc, V: StructDoc> StructDoc for BTreeMap<K, V>

Source§

impl<K: StructDoc, V: StructDoc, S> StructDoc for HashMap<K, V, S>

Source§

impl<T: Clone + StructDoc> StructDoc for Cow<'_, T>

Source§

impl<T: StructDoc> StructDoc for Option<T>

Source§

impl<T: StructDoc> StructDoc for [T; 1]

Source§

impl<T: StructDoc> StructDoc for [T; 2]

Source§

impl<T: StructDoc> StructDoc for [T; 3]

Source§

impl<T: StructDoc> StructDoc for [T; 4]

Source§

impl<T: StructDoc> StructDoc for [T; 5]

Source§

impl<T: StructDoc> StructDoc for [T; 6]

Source§

impl<T: StructDoc> StructDoc for [T; 7]

Source§

impl<T: StructDoc> StructDoc for [T; 8]

Source§

impl<T: StructDoc> StructDoc for [T; 9]

Source§

impl<T: StructDoc> StructDoc for [T; 10]

Source§

impl<T: StructDoc> StructDoc for [T; 11]

Source§

impl<T: StructDoc> StructDoc for [T; 12]

Source§

impl<T: StructDoc> StructDoc for [T; 13]

Source§

impl<T: StructDoc> StructDoc for [T; 14]

Source§

impl<T: StructDoc> StructDoc for [T; 15]

Source§

impl<T: StructDoc> StructDoc for [T; 16]

Source§

impl<T: StructDoc> StructDoc for [T; 17]

Source§

impl<T: StructDoc> StructDoc for [T; 18]

Source§

impl<T: StructDoc> StructDoc for [T; 19]

Source§

impl<T: StructDoc> StructDoc for [T; 20]

Source§

impl<T: StructDoc> StructDoc for [T; 21]

Source§

impl<T: StructDoc> StructDoc for [T; 22]

Source§

impl<T: StructDoc> StructDoc for [T; 23]

Source§

impl<T: StructDoc> StructDoc for [T; 24]

Source§

impl<T: StructDoc> StructDoc for [T; 25]

Source§

impl<T: StructDoc> StructDoc for [T; 26]

Source§

impl<T: StructDoc> StructDoc for [T; 27]

Source§

impl<T: StructDoc> StructDoc for [T; 28]

Source§

impl<T: StructDoc> StructDoc for [T; 29]

Source§

impl<T: StructDoc> StructDoc for [T; 30]

Source§

impl<T: StructDoc> StructDoc for [T; 31]

Source§

impl<T: StructDoc> StructDoc for [T; 32]

Source§

impl<T: StructDoc> StructDoc for &T

Source§

impl<T: StructDoc> StructDoc for &mut T

Source§

impl<T: StructDoc> StructDoc for [T]

Source§

impl<T: StructDoc> StructDoc for Box<T>

Source§

impl<T: StructDoc> StructDoc for BinaryHeap<T>

Source§

impl<T: StructDoc> StructDoc for BTreeSet<T>

Source§

impl<T: StructDoc> StructDoc for LinkedList<T>

Source§

impl<T: StructDoc> StructDoc for VecDeque<T>

Source§

impl<T: StructDoc> StructDoc for Rc<T>

Source§

impl<T: StructDoc> StructDoc for Arc<T>

Source§

impl<T: StructDoc> StructDoc for Vec<T>

Source§

impl<T: StructDoc> StructDoc for Cell<T>

Source§

impl<T: StructDoc> StructDoc for RefCell<T>

Source§

impl<T: StructDoc> StructDoc for PhantomData<T>

Source§

impl<T: StructDoc> StructDoc for Wrapping<T>

Source§

impl<T: StructDoc> StructDoc for Mutex<T>

Source§

impl<T: StructDoc> StructDoc for RwLock<T>

Source§

impl<T: StructDoc, S> StructDoc for HashSet<T, S>

Implementors§