Documentation

Documenting the generated entities could be challenging, if at all possible, unless specifically supported. FieldX provides such support by allowing you to use the doc argument. But before we get there, let's have a quick overlook of easier cases where the argument is not needed.

The most obvious case would be the struct itself. Cleared!

Then there are the fields. Their attached documentation is then used for the accessors and builder setter methods.

Then what are we left with? The builder struct; the method build() of the builder implementation; the builder() method of the main struct; the setters and the mutable accessors; ... and so on! Quite a few, huh?

This is exactly where the doc argument comes to bind them all... It has a very simple syntax:

doc(
    "This is line 1",
    "then there is line 2",
    "",
    "and we keep counting!"
)

Every string in the list is an individual line of documentation, ending with an implicit newline character. I.e., the above doc contains four lines of documentation; these make two paragraphs in the generated output. Since doc accepts any syntactically valid Rust literal string, the user is free to choose what they want to see between the brackets.

Let's see how it works in practice:

/// The struct.
#[fxstruct(get, builder(doc("This is our builder for the Book struct.")))]
pub struct Book {
    title:     String,
    author:    String,
    year:      u32,
    #[fieldx(optional)]
    signed_by: String,
    #[fieldx(
        set(
            doc(
                "Set the physical location of the book.",
                "",
                "I have no idea what else to add to the above.\n\nBut I just need another line here!",
            )
        ),
        builder(doc("Initial book location.")),
        inner_mut,
        default("unknown".to_string())
    )]
    location:  String,
}

Check out the result (the methods build() and builder() are using the default documentation):