Crate structdoc

Extract documentation out of types and make use of it at runtime.

The StructDoc trait describes types which know their own documentation at runtime. It can be derived (see the StructDoc documentation for deriving details). The Documentation is a type holding the actual documentation.

Motivation

Sometimes, an application needs some structured input from the user ‒ configuration, input files, etc. Therefore, the format needs to be documented somehow. But doing so manually has several disadvantages:

• Manual documentation tends to be out of sync.
• It needs additional manual work.
• If parts of the structure come from different parts of the application or even different libraries, the documentation needs to either be collected from all these places or written manually at a different place (making the chance of forgetting to update it even higher).

This crate tries to help with that ‒ it allows extracting doc strings and composing them together to form the documentation automatically, using procedural derive. The structure is guaranteed to match and the documentation strings are much more likely to be updated, as they are close to the actual definitions being changed.

It is able to use both its own and serde's attributes, because serde is very commonly used to read the structured data.

Examples

use std::num::NonZeroU32;

use serde_derive::Deserialize;
use structdoc::StructDoc;

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

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

#[derive(Deserialize, StructDoc)]
struct Circle {
    // Will flatten both on the serde side and structdoc, effectively creating a structure with
    // 3 fields for both of them.
    #[serde(flatten)]
    center: Point,

    /// The diameter of the circle.
    diameter: NonZeroU32,
}

println!("{}", Circle::document());

TODO

This crate is young and has some missing things:

• Probably some corner-cases are not handled properly. Also, not everything that can derive Deserialize can derive StructDoc yet.
• Some ability to manually traverse the documentation.
• Allow tweaking how the documentation is printed.
• Proper tests.
• Error handling during derive ‒ the error messages would need some improvements and some things are simply ignored. Furthermore, if you specify some nonsensical combination of attributes, you're as likely to get some garbage documentation out instead of error.
• There are plans to provide implementations for types from other crates, under feature flags.

In other words, let this crate generate the documentation, but skim the result before shipping to make sure it is correct and makes sense. Pull requests to fix bugs are indeed welcome.

Structs

Documentation	A representation of documentation.
Field	A documentation node with actual documentation text.
Flags	Flags on nodes of Documentation.

Enums

Arity	An arity of an container.
Tagging	A tagging of an enum.

Traits

StructDoc

Types that can provide their own documentation at runtime.

Type Definitions

Text	Text representation.

Derive Macros

StructDoc