help

Documentation

Overview

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).

Index

• Variables
• type Argument
  • func ForArgument(argRaw markers.Argument) Argument
  • func (a Argument) TypeString() string
• type CategoryDoc
  • func ByCategory(reg *markers.Registry, sorter SortGroup) []CategoryDoc
• type DetailedHelp
• type FieldHelp
• type MarkerDoc
  • func ForDefinition(defn *markers.Definition, maybeHelp *markers.DefinitionHelp) MarkerDoc
  • func (m MarkerDoc) AnonymousField() bool
  • func (m MarkerDoc) Empty() bool
• type SortGroup

Variables

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{}
)

Types

type Argument

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

func ForArgument(argRaw markers.Argument) Argument

ForArgument returns the equivalent documentation for a marker argument.

func (Argument) TypeString

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

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

CategoryDoc contains help information for all markers in a Category.

func ByCategory

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

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

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

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

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

func (m MarkerDoc) AnonymousField() bool

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

func (MarkerDoc) Empty

func (m MarkerDoc) Empty() bool

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

type SortGroup

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.