docgen

Guides

Document a config struct

Add a table of the fields of a struct. The default of each field comes from the code, so the table cannot drift from it.

v2/machine/machine.go

type Config struct {
    // Wait is how long the Lamp stays on. 0 means DefaultWait.
    Wait time.Duration
    // Tries is the number of blinks. 0 means 1, and it is at most MaxTries.
    Tries int
    // Name is a label.
    Name string
}
func NewLamp(cfg Config) (*Lamp, error) {
    if cfg.Tries > MaxTries {
        return nil, &docgen.ConfigError{Field: "Tries"}
    }
    l := &Lamp{wait: cfg.Wait, tries: cfg.Tries}
    if l.wait == 0 {
        l.wait = DefaultWait
    }
    if cfg.Tries == 0 {
        l.tries = 1
    }
    return l, nil
}

docs/machines/guide-config.md

Before
# Settings

<!-- docgen:config pkg=machine type=Config -->
<!-- /docgen:config -->
After
# Settings

<!-- docgen:config pkg=machine type=Config -->
| Field | Type | Default | Description |
|---|---|---|---|
| `Wait` | `time.Duration` | `DefaultWait` (250ms) | Wait is how long the Lamp stays on. 0 means DefaultWait. |
| `Tries` | `int` | `1` | Tries is the number of blinks. 0 means 1, and it is at most MaxTries. |
| `Name` | `string` | zero value | Name is a label. |
<!-- /docgen:config -->
Preview

Settings

Field Type Default Description
Wait time.Duration DefaultWait (250ms) Wait is how long the Lamp stays on. 0 means DefaultWait.
Tries int 1 Tries is the number of blinks. 0 means 1, and it is at most MaxTries.
Name string zero value Name is a label.

Tip: apply each default in an if that compares the field with its zero value, such as if cfg.Tries == 0 { l.tries = 1 }. A default that the code computes in another way is not in the table.

For all the rules and options, see docgen:config.

Source: docs/guides/config-tables.md