[−][src]Trait structdoc::StructDoc
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
fn document() -> Documentation
Returns the documentation for the type.
Examples
use structdoc::StructDoc; println!("Documentation: {}", Vec::<Option<String>>::document());