Struct Documenter 

pub struct Documenter<'d> { /* private fields */ }

Contains the option for documenting YAML

Implementations

impl<'d> Documenter<'d>

pub fn new() -> Self

Creates a default documenter

Example

let d = yaml_extras::Documenter::new();

pub fn description_field(self, field: &'d str) -> Self

Change the description field to describe a field that contains other field. Default: “description”“

E.g. if you have the following YAML structure:

foo:
    bar: true
    baz: false

You can document it with the following YAML code:

foo:
    __description__: This field is needed for foo because it contains nested fields
    bar: No need for inned __description__ since bar contains only a value
    baz: Same for baz

By default you shouldn’t need to change this, except if your YAML structure actually contains a field called __description__.

pub fn type_name(self, f: &'d dyn Fn(&ValueType) -> String) -> Self

Change the way to display types.

The default function is a sensible one for english, but for other languages or if you want to tweak the display (e.g. not printing the type’s name between parenthesis) you can change it.

Argument

• f: reference to a (&ValueType) -> String closure or function. It it responsible for returning the type name as string. Typically you will want to match on yaml_extras::document::ValueType and maybe call the yaml_extras_document_ValueType::to_str function, which is the default.

Example

let yaml = serde_yaml::from_str("foo: 42").unwrap();
let mut d = yaml_extras::Documenter::new()
    .type_name(&|t| format!(" (whatever)"));

let mut actual = d.apply_value(&yaml, None).unwrap();
assert_eq!(actual, "foo (whatever): 42");

d = d.type_name(&|t| String::new());
actual = d.apply_value(&yaml, None).unwrap();
assert_eq!(actual, "foo: 42");

pub fn format_key(self, f: &'d dyn Fn(KeyArgs<'_>) -> String) -> Self

Change the way Mappings keys are displayed.

Example

let yaml = serde_yaml::from_str::<serde_yaml::Value>(r#"foo: 42
bar: true"#).unwrap();
let actual = yaml_extras::Documenter::new()
    // Quite useless way to display the info
    .format_key(&|args| format!("{}!!!", args.key.to_uppercase()))
    .apply_value(&yaml, None)
    .unwrap();

assert_eq!(actual, "FOO!!!\nBAR!!!");

pub fn format_mapping(self, f: &'d dyn Fn(InnerArgs<'_>) -> String) -> Self

Change the way Mappings are displayed.

pub fn format_list(self, f: &'d dyn Fn(InnerArgs<'_>) -> String) -> Self

Change the way Sequences are displayed.

pub fn indent(self, indent: &'d str) -> Self

Change the indent. Default: 4 spaces.

Example

let d = yaml_extras::Documenter::new()
    .indent("\t");

pub fn apply_value( &self, value: &Value, description: Option<&Value>, ) -> Result<String>

Uses a YAML representation from a default struct to document an API or options in a YAML-looking way

The idea is to first generate a yaml representation with YourStruct::default() to get a mostly automated API description.

Arguments

• value: should correspond to a serde_yaml Value with the default values of your structure
• description: an optional serde_yaml value mirroring the value but with descriptions for fields you want to document. Use __description__ inside a Mapping to document the upper-level field.

Example

        let desc_yaml = r#"
foo:
    __description__: Description for foo
    bar: Description for bar
"#;
 
        let yaml = r#"
foo:
    bar: 42
"#;
 
        let expected = "# Description for foo
foo: \n    # Description for bar
    bar (Number): 42";
 
        let value: serde_yaml::Value = serde_yaml::from_str(&yaml).unwrap();
        let desc: serde_yaml::Value = serde_yaml::from_str(&desc_yaml).unwrap();
        let s = yaml_extras::Documenter::new()
            .apply_value(&value, Some(&desc))
            .unwrap();
        assert_eq!(s, expected);