controller-tools: Index | Files | Directories

package help

import ""

Package help contains utilities for actually writing out marker help.

Namely, it contains a series of structs (and helpers for producing them) that represent a merged view of marker definition and help that can be used for consumption by the pretty subpackage (for terminal help) or serialized as JSON (e.g. for generating HTML help).


Package Files

doc.go sort.go types.go


var (
    // SortByCategory sorts the markers by name and groups them by their help category.
    SortByCategory = sortByCategory{}

    // SortByOption sorts by the generator that the option belongs to.
    SortByOption = optionsSort{}

type Argument Uses

type Argument struct {
    // Type is the data type of the argument (string, bool, int, slice, any, raw, invalid)
    Type string `json:"type"`
    // Optional marks this argument as optional.
    Optional bool `json:"optional"`
    // ItemType contains the type of the slice item, if this is a slice
    ItemType *Argument `json:"itemType,omitempty"`

Argument is the type data for a marker argument.

func ForArgument Uses

func ForArgument(argRaw markers.Argument) Argument

ForArgument returns the equivalent documentation for a marker argument.

func (Argument) TypeString Uses

func (a Argument) TypeString() string

TypeString returns a string roughly equivalent (but not identical) to the underlying Go type that this argument would parse to. It's mainly useful for user-friendly formatting of this argument (e.g. help strings).

type CategoryDoc Uses

type CategoryDoc struct {
    Category string      `json:"category"`
    Markers  []MarkerDoc `json:"markers"`

CategoryDoc contains help information for all markers in a Category.

func ByCategory Uses

func ByCategory(reg *markers.Registry, sorter SortGroup) []CategoryDoc

ByCategory returns the marker help for markers in the given registry, grouped and sorted according to the given method.

type DetailedHelp Uses

type DetailedHelp struct {
    // Summary contains a one-line description.
    Summary string `json:"summary"`
    // Details contains further information.
    Details string `json:"details,omitempty"`

DetailedHelp contains both a summary and further details.

type FieldHelp Uses

type FieldHelp struct {
    // Name is the field name.
    Name string `json:"name"`
    // Argument is the type of the field.
    Argument `json:",inline"`

    // DetailedHelp contains the textual help for the field.
    DetailedHelp `json:",inline"`

FieldHelp contains information required to print documentation for a marker field.

type MarkerDoc Uses

type MarkerDoc struct {

    // Name is the name of the marker.
    Name string `json:"name"`
    // Target is the target (field, package, type) of the marker.
    Target string `json:"target"`

    // DetailedHelp is the textual help for the marker.
    DetailedHelp `json:",inline"`
    // Category is the general "category" that this marker belongs to.
    Category string `json:"category"`
    // DeprecatedInFavorOf marks that this marker shouldn't be used when
    // non-nil.  If also non-empty, another marker should be used instead.
    DeprecatedInFavorOf *string `json:"deprecatedInFavorOf,omitempty"`
    // Fields is the type and help data for each field of this marker.
    Fields []FieldHelp `json:"fields,omitempty"`

MarkerDoc contains information required to print documentation for a marker.

func ForDefinition Uses

func ForDefinition(defn *markers.Definition, maybeHelp *markers.DefinitionHelp) MarkerDoc

ForDefinition returns the equivalent marker documentation for a given marker definition and spearate help.

func (MarkerDoc) AnonymousField Uses

func (m MarkerDoc) AnonymousField() bool

AnonymousField chekcs if this is an single-valued marker (as opposed to having named fields).

func (MarkerDoc) Empty Uses

func (m MarkerDoc) Empty() bool

Empty checks if this marker has any arguments, returning true if not.

type SortGroup Uses

type SortGroup interface {
    // Less is equivalent to the Less function from sort, and is used to sort the markers.
    Less(*markers.Definition, *markers.Definition) bool
    // Group returns the "group" that a given marker belongs to.
    Group(*markers.Definition, *markers.DefinitionHelp) string

SortGroup knows how to sort and group marker definitions.


prettyPackage pretty contains utilities for formatting terminal help output, and a use of those to display marker help.

Package help imports 3 packages (graph) and is imported by 6 packages. Updated 2019-09-10. Refresh now. Tools for package owners.