docs

package
Version: v0.0.0-...-843189d Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 3, 2023 License: MPL-2.0 Imports: 5 Imported by: 29

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Category

type Category bool

type Default

type Default string

Default sets the Default of the field

type Details

type Details struct {
	// Description is the highlevel description of the plugin.
	Description string

	// Example is typically an hcl configuration snippit of using
	// the plugin.
	Example string

	// Input is the type of the value that the plugin accepts from the
	// previous plugin. This can be empty if the plugin does not use
	// any inputs.
	Input string

	// Output is the type of the value that the plugin outputs.
	Output string

	// Mappers is the list of mappers that the plugin makes available for
	// type conversion.
	Mappers []Mapper
}

Details documents highlevel information about a plugin.

type DocField

type DocField interface {
	SetField(name, synposis string, opts ...docOption) error
}

DocField contains a field that can be set - i.e. a Documentation or a SubFieldDoc

type Documentation

type Documentation struct {
	// contains filtered or unexported fields
}

Documentation allows a plugin to document its many wonderful features.

func New

func New(opts ...Option) (*Documentation, error)

New creates a new Documentation value.

func (*Documentation) AddMapper

func (d *Documentation) AddMapper(input, output, description string)

AddMapper adds a new Mapper value to the mappers in Documentation

func (*Documentation) Description

func (d *Documentation) Description(x string)

Description sets the Description field of the Documentation

func (*Documentation) Details

func (d *Documentation) Details() *Details

Details returns the formatted Details value from Documentation

func (*Documentation) Example

func (d *Documentation) Example(x string)

Example sets the Example field of the Documentation

func (*Documentation) Fields

func (d *Documentation) Fields() []*FieldDocs

Fields returns the formatted FieldDocs values for the fields

func (*Documentation) Input

func (d *Documentation) Input(x string)

Input sets the Input field of the Documentation

func (*Documentation) Output

func (d *Documentation) Output(x string)

Output sets the Output field of the Documentation

func (*Documentation) OverrideField

func (d *Documentation) OverrideField(f *FieldDocs) error

OverrideField sets the documentation for the given field directly.

func (*Documentation) OverrideRequestField

func (d *Documentation) OverrideRequestField(f *FieldDocs) error

OverrideField sets the documentation for the given request field directly.

func (*Documentation) OverrideTemplateField

func (d *Documentation) OverrideTemplateField(f *FieldDocs) error

OverrideField sets the documentation for the given template field directly.

func (*Documentation) RequestFields

func (d *Documentation) RequestFields() []*FieldDocs

RequestFields returns the formatted FieldDocs values for the request fields

func (*Documentation) SetField

func (d *Documentation) SetField(name, synposis string, opts ...docOption) error

SetField sets various documentation for the given field. If the field is already known, the documentation is merely updated. If the field is missing, it is created.

func (*Documentation) SetRequestField

func (d *Documentation) SetRequestField(name, synposis string, opts ...docOption) error

SetRequestField sets various documentation for the given request field. If the field is already known, the documentation is merely updated. If the field is missing, it is created.

func (*Documentation) SetTemplateField

func (d *Documentation) SetTemplateField(name, synposis string, opts ...docOption) error

SetTemplateField sets various documentation for the given template field. If the field is already known, the documentation is merely updated. If the field is missing, it is created.

func (*Documentation) SubFields

func (d *Documentation) SubFields(parent string, f func(d *SubFieldDoc)) *SubFieldDoc

Create sub-fields from existing parent docs.

func (*Documentation) TemplateFields

func (d *Documentation) TemplateFields() []*FieldDocs

TemplateFields returns the formatted FieldDocs values for the template fields

type EnvVar

type EnvVar string

EnvVar sets the EnvVar of the field

type Example

type Example string

Example gives the example usage, as it would be specified in HCL.

type FieldDocs

type FieldDocs struct {
	// Field is the name of the attribute
	Field string

	// Type is the hcl type of the attribute (int, string, etc)
	Type string

	// Synopsis is a short, one line description of the attribute
	Synopsis string

	// Summary is a longer, more in-depth description of the attribute.
	Summary string

	// Optional indicates of the attribute is optional or not.
	Optional bool

	// Default indicates the value of the attribute if the user does not set it.
	Default string

	// EnvVar indicates the operating system environment variable that will be
	// used to read the value from if the user does not set it.
	EnvVar string

	// Category indicates that this is not a field itself but a HCL block
	// that has fields underneath it.
	Category bool

	// Example indicates example usage, in HCL syntax
	Example string

	// SubFields is defined when this field is a category. It is the fields
	// in that category.
	SubFields []*FieldDocs
	// contains filtered or unexported fields
}

FieldDocs documents a specific attribute the plugin has available.

type Mapper

type Mapper struct {
	// Input is the type of the value that the mapper takes as input.
	Input string

	// Output is the type of the value that the mapper outputs.
	Output string

	// Description is a simple explanation of how the mapper converts the values.
	Description string
}

Mapper indicates the available mappers and what types they convert from and to.

type Option

type Option func(*Documentation) error

Option is implemented by various functions to automatically populate the Documentation.

func FromConfig

func FromConfig(v interface{}) Option

FromConfig populates the Documentation value by reading the struct members on the value. This is typically passed the value that is returned by the plugin's Config function.

func FromFunc

func FromFunc(v interface{}) Option

FromFunc fills in the documentation it can from the main function for the component: DeployFunc, ReleaseFunc, etc. v can be nil and this will do nothing.

This currently extracts:

  • Template fields from the result type if the result type is a concrete type (not an interface value).

func RequestFromStruct

func RequestFromStruct(v interface{}) Option

RequestFromStruct populates the Documentation's request information by reading the struct members on the value. Request information is configuration defined by a ConfigSourcer to be used as authentication and other non-config information.

type SubFieldDoc

type SubFieldDoc struct {
	// contains filtered or unexported fields
}

func SubFields

func SubFields(f func(d *SubFieldDoc)) *SubFieldDoc

DEPRECATED - use the method SubField instead. This breaks if you nest more than 1 layer deep.

func (*SubFieldDoc) Fields

func (d *SubFieldDoc) Fields() []*FieldDocs

Fields returns the formatted FieldDocs values for the fields

func (*SubFieldDoc) SetField

func (s *SubFieldDoc) SetField(name, synposis string, opts ...docOption) error

func (*SubFieldDoc) SubFields

func (s *SubFieldDoc) SubFields(parent string, f func(d *SubFieldDoc)) *SubFieldDoc

Create sub-fields from existing subfield docs.

type SummaryString

type SummaryString string

SummaryString sets the Summary of the field

func Summary

func Summary(in ...string) SummaryString

Summary creates a SummaryString by doing some light space editing and joining of the given array of strings. This is a convenience function for writing multi-line summaries that format well as Go code.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL