# Markers The marker kinds and their arguments. The text comes from the package doc of docgen. A marker has this form. Kinds `const`, `gomod` and `var` go inline in a sentence. Other kinds have the body on the lines between the two comments: ```text ``` - Package paths are relative to the module. - `pkg=session` also matches `transport/tcp/session` when exactly one package path ends that way. - File paths, and `cmd=`, are relative to the repository root. Each box is the output of a [`docgen:docgen`](#docgendocgen) marker over a page of the test fixture. ## Marker kinds ### docgen:output The output of a program, a command or an Example. docgen:output cmd= docgen:output exec="" docgen:output test=. The arguments: - `cmd=` is the standard output of `go run` on the Go program in that directory, relative to the repository root, from its nearest `go.mod`. - `exec=` is the standard output of a shell command, run with `sh -c` in the repository root. A nonzero exit status is an error. - `test=` is the expected output of an Example function, as written in its `// Output:` comment. `go test` fails when the real output differs, so the page cannot hold wrong output. Give the package and the function, such as `test=machine.ExampleLamp`. `test=machine.Example` is the Example of the package itself. The output must be the same on each run, or check fails. A program or command with no output gives an empty block, and an Example with an empty `// Output:` comment is an error. #### The output of an Example, with `test=` ``` go func ExampleLamp() { l, _ := machine.NewLamp(machine.Config{}) _ = l.Start(0) fmt.Println(l.State() == machine.LampOn) } ``` #### Before # Example #### After # Example ```text true ``` #### The output of a program or a command, with `cmd=` or `exec=` ``` go func main() { fmt.Println("hello from the fixture") } ``` module github.com/USA-RedDragon/docgen/v2 go 1.24.0 #### Before #### After ```text hello from the fixture ``` ```text module github.com/USA-RedDragon/docgen/v2 ``` ### docgen:code An excerpt of a file of the repository. docgen:code file= symbol= docgen:code file= region= docgen:code file= lines=- docgen:code file= The arguments: - `symbol=` in a Go file is one func, method (`Type.Method`), type, or const or var block, with no doc comment. An Example has no output comment. - `symbol=` in a YAML file is the block of the key at a dotted path, such as `jobs.test` of a workflow. A last segment `key[A:B]` is the items of the list at `key` from the item with name `A` to the item with name `B`, and `key[A]` is the one item `A`. - `symbol=` in a JSON or TOML file uses the same path form. In JSON the excerpt is `"key": value`. In TOML it is a key with its value, or a table `[a.b]` with its keys and sub-tables, and `key[A]` is an item of the array of tables `[[key]]`. An item is found by its `name` key, or by a number, its index from 0. `\.` is a dot in a key. - `symbol=` in a C file is the `#define` of Name or the definition of the function Name. - `region=` is the lines between the line `docgen:region ` and the next line `docgen:end`. Each mark is the whole line apart from comment syntax. In a page, a mark in code or in a marker body is text. Other excerpts of the file leave out those two lines. - `lines=` is those lines of the file. For a Go file the lines must hold whole declarations or statements. When the file changes, check and update fail. The error holds the new range when the old excerpt moved, and otherwise states that the range is out of date. A range past the last line is an error. - With none of these, the excerpt is the whole file. - `raw=true`, with `symbol=`, `lines=` or the whole file, keeps the text of the file: doc comments, region marks and the output comment of an Example. `symbol=package` in a Go file is then the package clause with its doc comment. Any other value is an error. An excerpt with no text is an error. On a scanned page, the excerpt is the text that update writes to that page. An excerpt of the page of its own marker is an error, and so are excerpts that do not settle in 8 passes. #### A Go declaration, with `symbol=` ``` go func (l *Lamp) Start(now time.Duration) error { if l.state == LampOn { return ErrBusy } if l.state == LampOff { l.state, l.until = LampOn, now+l.wait } return nil } ``` #### Before # Start a lamp #### After # Start a lamp ```go func (l *Lamp) Start(now time.Duration) error { if l.state == LampOn { return ErrBusy } if l.state == LampOff { l.state, l.until = LampOn, now+l.wait } return nil } ``` #### A YAML key, with `symbol=` ``` yaml jobs: test: env: GOFLAGS: -mod=readonly steps: - name: Get the code uses: actions/checkout@v6 - name: Run the tests run: go test ./... - name: Check the docs run: docgen check ``` #### Before #### After ```yaml env: GOFLAGS: -mod=readonly ``` ```yaml - name: Get the code uses: actions/checkout@v6 - name: Run the tests run: go test ./... ``` ```yaml - name: Check the docs run: docgen check ``` #### A JSON member, with `symbol=` ``` json { "server": { "port": 8080, "hosts": ["a.example", "b.example"] }, "jobs": [ {"name": "build", "run": "go build ./..."}, {"name": "test", "run": "go test ./..."}, {"name": "docs", "run": "docgen check"} ] } ``` #### Before #### After ```json "port": 8080 ``` ```json {"name": "build", "run": "go build ./..."}, {"name": "test", "run": "go test ./..."} ``` ```json {"name": "docs", "run": "docgen check"} ``` #### A TOML table or key, with `symbol=` ``` toml [server] port = 8080 # the default port hosts = [ "a.example", "b.example", ] [[jobs]] name = "build" run = "go build ./..." [[jobs]] name = "test" run = """ go vet ./... go test ./...""" ``` #### Before #### After ```toml [server] port = 8080 # the default port hosts = [ "a.example", "b.example", ] ``` ```toml hosts = [ "a.example", "b.example", ] ``` ```toml [[jobs]] name = "test" run = """ go vet ./... go test ./...""" ``` #### A C function or \#define, with `symbol=` ``` c #define LAMP_MAX_TRIES 3 static int tries; int lamp_start(int count) { if (count > LAMP_MAX_TRIES) { return -1; } tries = count; return 0; } ``` #### Before #### After ```c #define LAMP_MAX_TRIES 3 ``` ```c int lamp_start(int count) { if (count > LAMP_MAX_TRIES) { return -1; } tries = count; return 0; } ``` #### A region, a line range or a whole file ``` sh #!/bin/sh set -eu # docgen:region setup go mod download go build ./... # docgen:end go test ./... ``` #### Before #### After ```sh go mod download go build ./... ``` ```sh #!/bin/sh set -eu ``` ```sh #!/bin/sh set -eu go mod download go build ./... go test ./... ``` #### An excerpt with its comments and marks, with `raw=true` ``` go // Package machine is a small state machine for the docgen tests. // // # Rates // // A Lamp blinks at these rates: // - slow, every [DefaultWait] // - fast, every period // // # Other // // Not copied. package machine ``` ``` go // Start turns the Lamp on. It returns ErrBusy while the Lamp is on. func (l *Lamp) Start(now time.Duration) error { if l.state == LampOn { return ErrBusy } if l.state == LampOff { l.state, l.until = LampOn, now+l.wait } return nil } ``` ``` sh #!/bin/sh set -eu # docgen:region setup go mod download go build ./... # docgen:end go test ./... ``` #### Before # Keep the comments #### After # Keep the comments ```go // Start turns the Lamp on. It returns ErrBusy while the Lamp is on. func (l *Lamp) Start(now time.Duration) error { if l.state == LampOn { return ErrBusy } if l.state == LampOff { l.state, l.until = LampOn, now+l.wait } return nil } ``` ```go // Package machine is a small state machine for the docgen tests. // // # Rates // // A Lamp blinks at these rates: // - slow, every [DefaultWait] // - fast, every period // // # Other // // Not copied. package machine ``` ```sh #!/bin/sh set -eu # docgen:region setup go mod download go build ./... # docgen:end go test ./... ``` ### docgen:config A table of the fields of a struct type, with the columns Field, Type, Default and Description. docgen:config pkg= type= [print=] `type=` is a struct type of the package, exported or not. It can also be an alias or a defined type of a struct type, or of an instance of a generic struct type, such as `type Small = Gen[int]`. The rows: - Each exported field is one row, in source order. - An embedded field with an exported type name, such as `Timing` or `*url.URL`, is one row. The type name is the field name. - An unexported field has no row. - An embedded field with an unexported type name has no row. - The fields of an embedded struct have no rows. The Field column holds the field name. The Type column holds the field type as it is in Go source in the package of the marker: - A type of another package has the package name, such as `time.Duration` or `map[string]*url.URL`. - Pointers, slices, maps, channels, funcs, struct types with their tags and instances of generic types, such as `q.G[string]`, are as in Go source. - An alias is the alias name. - A cgo type has the prefix `C.`, such as `C.int`. The Description column holds the doc comment of the field: - With no doc comment, it holds the trailing comment. With neither, it is empty. - Each name in one declaration, such as `A, B int // The limits.`, has that comment. - For an alias or a defined type of a struct, the comments come from the declaration of that struct, also in another package. - Line breaks and blank lines become spaces. - A `|` becomes `\|`. Other text, such as HTML, backticks and doc links, stays as written, so Markdown renders it. The Default column holds each default of the field as written in the code, with its value in parentheses. Two or more defaults are joined with "or", in the order of file names and lines. A default written the same way twice is there once. A field with no default has one of these: - "not machine-readable; see the description", when the field doc has a phrase from the list below. - "zero value", when it does not. The phrases match in any case and across a line break: `0 means`, `nil means`, `zero means`, `empty means`, `a zero means`, `an empty means`, `defaults to` and `by default`. Other text, such as "Zero value means" or "The default is", gives "zero value". docgen finds a default in the files of the package of `pkg=`. Files that end in `_test.go`, and the code of other packages, do not count. For a default that is set in another package, use `pkg=` of that package and an alias of the type there, such as `type Config = server.Config`. A default is the value V of an assignment `y = V` in this form: if x == 0 { y = V } x and y are copies of the same field. A copy is one of these: - The field itself, such as `c.Wait`, for any value of the struct type. - A variable or field that gets a copy: `wait := c.Wait`, `wait = c.Wait` or `var wait = c.Wait`. - A field that gets a copy in a composite literal, such as `wait` in `Lamp{wait: c.Wait}`. Then `l.wait` is a copy for any `Lamp` l. - A parameter of a function or method of the package that gets a copy as its argument, such as `n` of `func use(n int)` in `use(c.Wait)`. The forms of the test: - The condition of an `if`, or a case of a `switch` with no tag. - `x == Z` or `x <= Z`, where Z is `0`, `0.0`, `""`, `nil`, or a constant with the value 0 or "". - The `if` can have an init statement: `if x := c.Wait; x == 0`. - The assignment can be in a nested `if` or block of the body. These do not count: - The tests `0 == x`, `x < 1`, `!x`, `x == false`, `len(x) == 0` and `x == 0 && y`. - A `switch x` with a tag, and the `else` of an `if`. - An assignment with `:=` or `+=`, with two or more targets, or in a `for` or `range` loop or a func literal. `print=` sets the text of the value in parentheses, with the same choices as `docgen:const`. With no `print=`, the `print` setting applies. Its default is `go`. - `go`: the value as `fmt.Sprint` prints it, with the String, Error, Format and GoString methods of its type: `DefaultWait` (250ms). A literal, such as `3`, has no value, unless its type has one of these methods: `80` (port-80). - `raw`: the underlying value, with no method: `DefaultWait` (250000000). A literal has no value. - `name`: the name of the one constant of the type with the value, as for `docgen:const`: `LevelLow + 1` (LevelHigh), or `60 * time.Second` (time.Minute). A literal has no value, and neither does a value with no such constant. - A fmt verb, such as `%x`: the value with that verb, also of a literal: `DefaultColor` (ffaa00). A default that is not a constant, such as `hold` or `new(int)`, has no value with any `print=`. A value with the same text as its default, such as `-1`, has no parentheses. A value of a type with one of these methods comes from one `go test` run of the package, as for `docgen:const`. These are errors: - `pkg=` with no package, or `type=` that is not a type of the package. - A type that is not a struct, a generic type, or a struct with no row. - An empty `print=`, or a value that is not `go`, `raw`, `name` or one fmt verb. - A verb that a default cannot use, such as `%d` for a string. - `print=name` when two constants of the type have the value. #### Defaults as Go prints them ``` 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 } ``` ``` go 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 } ``` #### Before # Settings #### After # 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. | #### Underlying values, with `print=raw` ``` go const DefaultWait = 250 * time.Millisecond ``` ``` 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 } ``` ``` go 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 } ``` #### Before #### After | Field | Type | Default | Description | |---|---|---|---| | `Wait` | `time.Duration` | `DefaultWait` (250000000) | 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. | #### Constant names, with `print=name` ``` go const ( // LevelOff gives no light. LevelOff Level = iota // LevelLow gives some light. LevelLow // LevelHigh gives full light. LevelHigh ) ``` ``` go type Look struct { // Level is the brightness at start. Level Level // Color is an RGB color. Color uint32 } ``` ``` go func NewLook(l Look) Look { if l.Level == LevelOff { l.Level = LevelLow + 1 } if l.Color == 0 { l.Color = DefaultColor } return l } ``` #### Before #### After | Field | Type | Default | Description | |---|---|---|---| | `Level` | `Level` | `LevelLow + 1` (LevelHigh) | Level is the brightness at start. | | `Color` | `uint32` | `DefaultColor` | Color is an RGB color. | #### Values with a fmt verb, such as `print=%x` ``` go const DefaultColor = 0xffaa00 ``` ``` go type Look struct { // Level is the brightness at start. Level Level // Color is an RGB color. Color uint32 } ``` ``` go func NewLook(l Look) Look { if l.Level == LevelOff { l.Level = LevelLow + 1 } if l.Color == 0 { l.Color = DefaultColor } return l } ``` #### Before #### After | Field | Type | Default | Description | |---|---|---|---| | `Level` | `Level` | `LevelLow + 1` (2) | Level is the brightness at start. | | `Color` | `uint32` | `DefaultColor` (ffaa00) | Color is an RGB color. | #### A field whose default is not machine-readable ``` go type Steps struct { // Step is the change of one press. 0 means 1. Step int } ``` ``` go func NewSteps(s Steps) Steps { if s.Step < 1 { s.Step = 1 } return s } ``` #### Before #### After | Field | Type | Default | Description | |---|---|---|---| | `Step` | `int` | not machine-readable; see the description | Step is the change of one press. 0 means 1. | #### A field with no default ``` go type Tag struct { // Name is a label next to the Dimmer. Name string } ``` #### Before #### After | Field | Type | Default | Description | |---|---|---|---| | `Name` | `string` | zero value | Name is a label next to the Dimmer. | #### Rows of embedded fields ``` go type Timing struct { // Fade is the time of a change of level. Fade time.Duration } ``` ``` go type counts struct { // Presses is the number of presses. Presses int } ``` ``` go type Setup struct { // Timing holds the times. Timing counts // Look is the light at start. Look Look } ``` #### Before #### After | Field | Type | Default | Description | |---|---|---|---| | `Timing` | `Timing` | zero value | Timing holds the times. | | `Look` | `Look` | zero value | Look is the light at start. | #### Field types from other packages ``` go type Group struct { // Main is the first lamp. Main *machine.Lamp // Spares are the other lamps. Spares []machine.Lamp // States holds the state of each lamp by name. States map[string]machine.LampState } ``` #### Before #### After | Field | Type | Default | Description | |---|---|---|---| | `Main` | `*machine.Lamp` | zero value | Main is the first lamp. | | `Spares` | `[]machine.Lamp` | zero value | Spares are the other lamps. | | `States` | `map[string]machine.LampState` | zero value | States holds the state of each lamp by name. | #### A description from a trailing comment ``` go type Range struct { Min Level // Min is the lowest level. // Max is the highest level. Max Level // This comment is not in the table. } ``` #### Before #### After | Field | Type | Default | Description | |---|---|---|---| | `Min` | `Level` | zero value | Min is the lowest level. | | `Max` | `Level` | zero value | Max is the highest level. | ### docgen:configulator The reference table of a config type of [configulator](https://github.com/USA-RedDragon/configulator): each key, with its type, default, environment variable, flag and description. docgen:configulator pkg= type= [env=] [envsep=] [flagsep=] ``` go type Config struct { Name string `name:"name" default:"lamp" description:"name of the program"` Server Server `name:"server"` } ``` ``` go type Server struct { Port int `name:"port" default:"8080" description:"port of the server"` } ``` #### Before #### After | Key | Type | Default | Environment | Flag | Description | |---------------|---------|---------|--------------------|-----------------|---------------------| | `name` | string | `lamp` | `APP_NAME` | `--name` | name of the program | | `server.port` | integer | `8080` | `APP_SERVER__PORT` | `--server-port` | port of the server | ### docgen:const The value of a constant, or of a package-level var with a constant initial value, exported or not. It goes inline in a sentence. docgen:const pkg= name= [print=] [code=false] `print=` sets how the value prints: - `print=go` is the default. The value prints as `fmt.Sprint` prints it, with the String, Error, Format and GoString methods of its type, so `250 * time.Millisecond` is `250ms`, strings have no quotes and `1e6` is `1e+06`. - `print=raw` is the underlying value with no method, and runs no code: `4001` for a port with a String method, `1` for an enum, and `1500000000` for a `time.Duration` of 1.5s. - `print=name` is the name of the one constant of the type with the value, from the package of the marker and then the package of the type. A constant of the package of the type is exported and has the package name, as in Go source: `time.Minute` for `60 * time.Second`. - `print=%d`, or any other fmt verb, is the value with that verb. An empty value prints as `""`, and line endings in a value print as spaces. A verb that the value cannot use is an error. An integer too large for its default type prints its exact value. A type with a print method runs in one `go test` for each package, so the tests of that package must compile. With `code=false`, the value has no backticks: 250ms in place of `250ms`. Any other value of `code=` is an error. #### A value as Go prints it ``` go const DefaultWait = 250 * time.Millisecond ``` #### Before The default wait is . #### After The default wait is `250ms`. #### A value in another form, with `print=` ``` go package machine import "fmt" // Port is a network port. type Port uint16 // String returns the port as text. func (p Port) String() string { return fmt.Sprintf("port %d", uint16(p)) } // PortWeb is the port of the web server. const PortWeb Port = 8080 // Listen is the port of a new Lamp. var Listen = PortWeb ``` #### Before - Default: - `go`: - `raw`: - `name`: - `%06d`: #### After - Default: `port 8080` - `go`: `port 8080` - `raw`: `8080` - `name`: `PortWeb` - `%06d`: `008080` #### A value with no backticks, with `code=false` ``` go const DefaultWait = 250 * time.Millisecond ``` #### Before The default wait is . #### After The default wait is 250ms. ### docgen:errors A table of the errors named in the doc comments of the constructors and methods of a type. Names resolve in the package, the module packages that it imports and the root package of the module. Consts and vars of any error type count. docgen:errors pkg= type= ``` go var ( // ErrBusy is returned by Start while the Lamp is on. ErrBusy = errors.New("machine: busy") // ErrOff is returned by Stop while the Lamp is off. ErrOff = errors.New("machine: off") ) ``` ``` go // NewLamp returns a Lamp. It returns a *docgen.ConfigError for a Tries // above MaxTries. 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 } ``` ``` go // Start turns the Lamp on. It returns ErrBusy while the Lamp is on. func (l *Lamp) Start(now time.Duration) error { if l.state == LampOn { return ErrBusy } if l.state == LampOff { l.state, l.until = LampOn, now+l.wait } return nil } ``` ``` go // Stop turns the Lamp off. It returns ErrOff while the Lamp is off. func (l *Lamp) Stop() error { if l.state != LampOn { return ErrOff } l.off() return nil } ``` ``` go // Package docgen is the fixture root package of the docgen tests. package docgen // ConfigError is the error of a constructor for a field with a value out // of range. type ConfigError struct{ Field string } func (e *ConfigError) Error() string { return "bad " + e.Field } ``` #### Before # Errors #### After # Errors | Error | Returned by | Meaning | |---|---|---| | [`docgen.ConfigError`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2#ConfigError) | `NewLamp` | ConfigError is the error of a constructor for a field with a value out of range. | | [`machine.ErrBusy`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/machine#ErrBusy) | `Lamp.Start` | ErrBusy is returned by Start while the Lamp is on. | | [`machine.ErrOff`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/machine#ErrOff) | `Lamp.Stop` | ErrOff is returned by Stop while the Lamp is off. | ### docgen:states The states and the transitions of a state machine, and an SVG diagram of them. docgen:states pkg= type= [run=] [diagram=] The diagram goes in `states/-.svg` next to the page. `diagram=` gives another path, relative to the page, which must end in `.svg` and must not be a scanned page. Two machines with one diagram file are an error. `type=` can be an alias of a type of the package. Value receiver methods, promoted methods and methods with no receiver name are not recorded, and the output lists them under Not recorded. #### A state machine ``` go type LampState uint8 ``` ``` go const ( // LampOff gives no light. LampOff LampState = iota // LampOn gives light. LampOn // LampBroken never gives light again. LampBroken ) ``` ``` go func (l *Lamp) State() LampState { return l.state } ``` ``` go func (l *Lamp) Start(now time.Duration) error { if l.state == LampOn { return ErrBusy } if l.state == LampOff { l.state, l.until = LampOn, now+l.wait } return nil } ``` ``` go func (l *Lamp) Stop() error { if l.state != LampOn { return ErrOff } l.off() return nil } ``` ``` go func (l *Lamp) Tick(now time.Duration) { if l.state == LampOn && now >= l.until { l.off() } } ``` ``` go func (l *Lamp) Break() { l.state = LampBroken } ``` ``` go func (l *Lamp) off() { l.state = LampOff } ``` ``` go func TestLamp(t *testing.T) { l, err := NewLamp(Config{}) if err != nil { t.Fatal(err) } _ = l.Start(0) l.Tick(DefaultWait) _ = l.Start(0) _ = l.Stop() l.Break() } ``` #### Before # The lamp #### After # The lamp States of [`Lamp`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/machine#Lamp), from [`Lamp.State`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/machine#Lamp.State): | State | Meaning | Seen in tests | |---|---|---| | [`LampOff`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/machine#LampOff) | LampOff gives no light. | yes, first state | | [`LampOn`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/machine#LampOn) | LampOn gives light. | yes | | [`LampBroken`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/machine#LampBroken) | LampBroken never gives light again. | yes | Transitions seen in tests: | From | Method call | To | |---|---|---| | LampOff | `Start` | LampOn | | LampOff | `Break` | LampBroken | | LampOn | `Stop`, `Tick` | LampOff | ![Transitions of Lamp](states/machine-lamp.svg) #### Some of the tests and another diagram path, with `run=` and `diagram=` ``` go // Package door is a state machine with its own tests, for the run= argument. package door // State is the state of a Door. type State uint8 // The State values. const ( // StateClosed is shut. StateClosed State = iota // StateOpen is open. StateOpen ) // Door opens and closes. type Door struct{ state State } // State returns the state of the Door. func (d *Door) State() State { return d.state } // Open opens the Door. func (d *Door) Open() { d.state = StateOpen } // Close closes the Door. func (d *Door) Close() { d.state = StateClosed } ``` ``` go func TestOpen(t *testing.T) { var d Door d.Open() } ``` #### Before #### After States of [`Door`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/door#Door), from [`Door.State`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/door#Door.State): | State | Meaning | Seen in tests | |---|---|---| | [`StateClosed`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/door#StateClosed) | StateClosed is shut. | yes, first state | | [`StateOpen`](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/door#StateOpen) | StateOpen is open. | yes | Transitions seen in tests: | From | Method call | To | |---|---|---| | StateClosed | `Open` | StateOpen | ![Transitions of Door](states/door-open.svg) ### docgen:doc A doc comment as Markdown: the package doc, or the doc of a type, func, method (`Type.Method`), const or var, or one `# heading` section of it. docgen:doc pkg= [name=] [section=] A `pkg=` that names a directory outside the module, such as a tool with a `go.mod` of its own, is the package doc of that directory. Its path is relative to the repository root. A name with no doc comment and a `section=` with no text are errors. Text in backticks in a doc comment is a code span. #### The doc comment of one declaration, with `name=` ``` go // Start turns the Lamp on. It returns ErrBusy while the Lamp is on. func (l *Lamp) Start(now time.Duration) error { if l.state == LampOn { return ErrBusy } if l.state == LampOff { l.state, l.until = LampOn, now+l.wait } return nil } ``` #### Before # Start #### After # Start Start turns the Lamp on. It returns ErrBusy while the Lamp is on. #### A package doc, or one section of it, with `section=` ``` go // Package docgen is the fixture root package of the docgen tests. package docgen // ConfigError is the error of a constructor for a field with a value out // of range. type ConfigError struct{ Field string } func (e *ConfigError) Error() string { return "bad " + e.Field } ``` ``` go // Package machine is a small state machine for the docgen tests. // // # Rates // // A Lamp blinks at these rates: // - slow, every [DefaultWait] // - fast, every period // // # Other // // Not copied. package machine ``` #### Before #### After Package docgen is the fixture root package of the docgen tests. A Lamp blinks at these rates: - slow, every [DefaultWait](https://pkg.go.dev/github.com/USA-RedDragon/docgen/v2/machine#DefaultWait) - fast, every period ### docgen:gomod A line of the `go.mod` of the module, or of the `go.mod` at `file=`. It goes inline in a sentence. docgen:gomod field= [file=] [code=false] With `code=false`, the value has no backticks, as for `docgen:const`. module github.com/USA-RedDragon/docgen/v2 go 1.24.0 module example.com/tool go 1.24.0 toolchain go1.24.1 #### Before - Module: - Go: - Module of the tool: - Toolchain of the tool: #### After - Module: `github.com/USA-RedDragon/docgen/v2` - Go: `1.24.0` - Module of the tool: `example.com/tool` - Toolchain of the tool: `go1.24.1` #### A Go version with no backticks, with `code=false` module github.com/USA-RedDragon/docgen/v2 go 1.24.0 #### Before This module needs Go or later. #### After This module needs Go 1.24.0 or later. ### docgen:usage The usage of a command. docgen:usage cmd= [args=""] docgen builds the command in that directory, relative to the repository root, and runs it with `-h`. With `args=`, the arguments are that value, split on spaces, such as `args="help config"` or `args=--help`. In the value, `\"` starts and ends an argument with spaces: `args="--name \"a b\""`. A build failure, a panic, an exit status other than 0, 1 or 2, or output with no line that starts with usage, in any letter case, and no flag line, is an error. This also applies to arguments that do not ask for help, so a command such as `version` must print a usage line or a flag line, such as `usage: tool version`. ``` go func main() { n := flag.Int("n", 3, "how many lines to print") flag.Parse() for i := 0; i < *n; i++ { fmt.Println(i) } } ``` #### Before # Flags #### After # Flags ```text Usage of tool: -n int how many lines to print (default 3) ``` #### The usage of a help command, with `args=` ``` go func main() { config := flag.NewFlagSet("lamp config", flag.ExitOnError) config.Duration("wait", 0, "the time before the lamp turns on") if len(os.Args) == 3 && os.Args[1] == "help" && os.Args[2] == "config" { config.SetOutput(os.Stdout) config.Usage() return } fmt.Println("usage: lamp [arguments]") } ``` #### Before # The config command #### After # The config command ```text Usage of lamp config: -wait duration the time before the lamp turns on ``` ### docgen:var The value of a variable of the `vars` setting, as a code span. It goes inline in a sentence. docgen:var name= [print=] [code=false] A key that is not in `vars` is an error. The value is a string: - `print=go`, the default, and `print=raw` are the value as it is. - `print=%q`, or any other fmt verb, is the string with that verb: `"v1.2.3"`. A verb that a string cannot use, such as `%d`, is an error. - `print=name` is an error, since a value of `vars` is not a constant. - With `code=false`, the value has no backticks, as for `docgen:const`. The boxes of `docgen:var` and `docgen:text` use this `.docgen.yaml`: ``` yaml vars: version: v1.2.3 ``` ``` yaml vars: version: v1.2.3 ``` #### Before The current version is . #### After The current version is `v1.2.3`. #### A quoted value, with `print=%q` ``` yaml vars: version: v1.2.3 ``` #### Before The quoted version is . #### After The quoted version is `"v1.2.3"`. ### docgen:text Text from a template, in which `vars` values replace the keys. With no `code=`, the text goes inline in a sentence. With `code=`, it is a code block in that language, and `code="text"` is a block with no highlighting, so a value can go in a code block, where markers are text. docgen:text text="