fb32886775
- help <command> and <command> --help print Description, Usage,
Arguments, Options with defaults, Global options, Help and Examples
- Command.Examples and Command.Hidden (appended, additive); list --all
shows hidden commands, list --format=json prints a bonfire.Listing
- CheckDocs reports commands lacking description, long help, examples or
argument and option descriptions
- Error block with the ERROR badge, WithHint explanation and Try lines
({bin} replaced), cobra suggestions as Try, -v error chain, messages
scrubbed by sunscreen; Reported errors print nothing and exit 1
56 lines
1.7 KiB
Go
56 lines
1.7 KiB
Go
package bonfire
|
|
|
|
import (
|
|
"slices"
|
|
"strings"
|
|
)
|
|
|
|
// DocProblem lists what one command's documentation lacks.
|
|
type DocProblem struct {
|
|
// Command is the command name.
|
|
Command string
|
|
// Missing names each gap: "description", "long help", "examples",
|
|
// "argument <name> description" or "option --<name> description".
|
|
Missing []string
|
|
}
|
|
|
|
// String formats the problem as "<command>: missing description, examples".
|
|
func (p DocProblem) String() string {
|
|
return p.Command + ": missing " + strings.Join(p.Missing, ", ")
|
|
}
|
|
|
|
// CheckDocs reports every command that lacks a description, long help, at
|
|
// least one example, or a description of one of its arguments or options,
|
|
// sorted by command name. It only reports: the framework's own test fails
|
|
// on a problem, plugin repositories log them.
|
|
func CheckDocs(commands []Command) []DocProblem {
|
|
var problems []DocProblem
|
|
for _, c := range commands {
|
|
var missing []string
|
|
if strings.TrimSpace(c.Description) == "" {
|
|
missing = append(missing, "description")
|
|
}
|
|
if strings.TrimSpace(c.Long) == "" {
|
|
missing = append(missing, "long help")
|
|
}
|
|
if len(c.Examples) == 0 {
|
|
missing = append(missing, "examples")
|
|
}
|
|
for _, a := range c.Args {
|
|
if strings.TrimSpace(a.Description) == "" {
|
|
missing = append(missing, "argument "+a.Name+" description")
|
|
}
|
|
}
|
|
for _, f := range c.Flags {
|
|
if strings.TrimSpace(f.Description) == "" {
|
|
missing = append(missing, "option --"+f.Name+" description")
|
|
}
|
|
}
|
|
if len(missing) > 0 {
|
|
problems = append(problems, DocProblem{Command: c.Name, Missing: missing})
|
|
}
|
|
}
|
|
slices.SortStableFunc(problems, func(a, b DocProblem) int { return strings.Compare(a.Command, b.Command) })
|
|
return problems
|
|
}
|