docs

func DefaultFlagTypeMatcher ¶

func DefaultFlagTypeMatcher(expr ast.Expr) bool

DefaultFlagTypeMatcher matches the urfave/cli/v3 core flag composite literals: BoolFlag, StringFlag, IntFlag and StringSliceFlag. Custom flag types are intentionally not matched here — see LongDescriptions for the extension mechanism.

func LongDescriptionFunc ¶

func LongDescriptionFunc(
	descs map[string]*LongDescription,
	fb LongDescriptionFallback,
) func(*PluginArg) *LongDescription

LongDescriptionFunc returns a template function that resolves a PluginArg's long description by first consulting descs and then invoking fb when no extracted description is available. Pass nil for fb to disable the fallback and have missing entries return nil directly.

Typical usage from a renderer:

funcs["longDesc"] = docs.LongDescriptionFunc(descs, docs.ShortDescriptionFallback)

Or, when no fallback is wanted:

funcs["longDesc"] = docs.LongDescriptionFunc(descs, nil)

func LongDescriptionMarkdown ¶

func LongDescriptionMarkdown(d *LongDescription) string

LongDescriptionMarkdown renders a structured LongDescription as a markdown-ready string. Line breaks inside a paragraph collapse to a single space so markdown renderers flow the text as one sentence; each paragraph is prefixed with " " to visually align with the short Description line that precedes it.

func LongDescriptionYAMLBlock ¶

func LongDescriptionYAMLBlock(d *LongDescription, indent string) string

LongDescriptionYAMLBlock renders a structured LongDescription as the body of a YAML literal block scalar. Every source line is prefixed with indent; paragraphs are separated by a blank line so the visual structure of the original comment is preserved end-to-end; the separator blank lines carry no trailing whitespace.

The function is the format-agnostic building block — it knows about YAML's `|` literal-block rules but not about any specific data schema. Consumers compose the surrounding "key: |" line themselves (the key name and nesting depth vary per consumer and determine the required indent).

func LongDescriptions ¶

func LongDescriptions(sourcePath string, matchers ...FlagTypeMatcher) (map[string]*LongDescription, error)

LongDescriptions parses sourcePath and extracts a LongDescription for every flag composite literal whose type matches at least one of the supplied matchers (OR semantics; evaluation short-circuits at the first match). When matchers is empty, only DefaultFlagTypeMatcher is applied.

A // comment block directly above an &<flag>Flag{...} literal is treated as the long docs description; a blank line in the source between the comment and the literal breaks the association.

A typical call site that wants both urfave core flags and wp-plugin-go custom flag types:

docs.LongDescriptions(
    "plugin/plugin.go",
    docs.DefaultFlagTypeMatcher,
    docs.SelectorMatcher("plugin_cli", "StringMapFlag", "DeepStringMapFlag"),
)

func LongDescriptionsFor ¶

func LongDescriptionsFor(sourcePath string, matchers ...FlagTypeMatcher) map[string]*LongDescription

LongDescriptionsFor is the template-data convenience wrapper around LongDescriptions. It normalises flag names so "upload.metadata" matches the env-derived "upload_metadata", and returns an empty map (instead of an error) when sourcePath is empty or unparseable, so a missing source never breaks a docs pipeline.

func ToMarkdown ¶

func ToMarkdown(app *cli.Command) (string, error)

ToMarkdown creates a markdown string for the `*App` without long descriptions. It is a convenience wrapper around ToMarkdownWithSource that passes an empty sourcePath.

func ToMarkdownWithSource ¶

func ToMarkdownWithSource(app *cli.Command, sourcePath string) (string, error)

ToMarkdownWithSource creates a markdown string for the `*App`. If sourcePath points to a readable Go source file, long descriptions are extracted from leading doc comments above each flag's composite literal and merged into the rendered output. An empty sourcePath disables long description lookup. The function errors if either parsing or writing of the string fails.