encoder

Documentation

Index

• Constants
• type Appearance
• type CommentsFlags
• type Doc
  • func (d *Doc) AddExample(name string, value interface{})
  • func (d *Doc) Describe(field string, short bool) string
  • func (d *Doc) Field(i int) *Doc
• type Documented
• type Encoder
  • func NewEncoder(value interface{}, opts ...Option) *Encoder
  • func (e *Encoder) Encode() ([]byte, error)
  • func (e *Encoder) Marshal() (*yaml.Node, error)
• type Example
  • func (e *Example) GetValue() interface{}
  • func (e *Example) Populate(index int)
• type FileDoc
  • func (fd *FileDoc) Encode() ([]byte, error)
  • func (fd *FileDoc) Write(path, frontmatter string) error
• type Option
  • func WithComments(flags CommentsFlags) Option
• type Options

Constants

const (
	// HeadComment populates `yaml.Node` `HeadComment`.
	HeadComment = iota
	// LineComment populates `yaml.Node` `LineComment`.
	LineComment
	// FootComment populates `yaml.Node` `FootComment`.
	FootComment
)

Types

type Appearance

type Appearance struct {
	TypeName  string
	FieldName string
}

Appearance of a type in a different type.

type CommentsFlags

type CommentsFlags int

CommentsFlags comments encoding flags type.

const (
	// CommentsDisabled renders no comments.
	CommentsDisabled CommentsFlags = 0
	// CommentsExamples enables commented yaml examples rendering.
	CommentsExamples CommentsFlags = 1 << iota
	// CommentsDocs enables rendering each config field short docstring.
	CommentsDocs
	// CommentsAll renders all comments.
	CommentsAll = CommentsExamples | CommentsDocs
)

type Doc

type Doc struct {
	// Comments stores foot, line and head comments.
	Comments [3]string
	// Fields contains fields documentation if related item is a struct.
	Fields []Doc
	// Examples list of example values for the item.
	Examples []*Example
	// Values is only used to render valid values list in the documentation.
	Values []string
	// Description represents the full description for the item.
	Description string
	// Name represents struct name or field name.
	Name string
	// Type represents struct name or field type.
	Type string
	// Note is rendered as a note for the example in markdown file.
	Note string
	// AppearsIn describes back references for the type.
	AppearsIn []Appearance
}

Doc represents a struct documentation rendered from comments by docgen.

func (*Doc) AddExample

func (d *Doc) AddExample(name string, value interface{})

AddExample adds a new example snippet to the doc.

func (*Doc) Describe

func (d *Doc) Describe(field string, short bool) string

Describe returns a field description.

func (*Doc) Field

func (d *Doc) Field(i int) *Doc

Field gets field from the list of fields.

type Documented

type Documented interface {
	// Doc requests documentation object.
	Doc() *Doc
}

Documented is used to check if struct has any documentation defined for it.

type Encoder

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

Encoder implements config encoder.

func NewEncoder

func NewEncoder(value interface{}, opts ...Option) *Encoder

NewEncoder initializes and returns an `Encoder`.

func (*Encoder) Encode

func (e *Encoder) Encode() ([]byte, error)

Encode converts value to yaml.

func (*Encoder) Marshal

func (e *Encoder) Marshal() (*yaml.Node, error)

Marshal converts value to YAML-serializable value (suitable for MarshalYAML).

type Example

type Example struct {
	Name string
	// contains filtered or unexported fields
}

Example represents one example snippet for a type.

func (*Example) GetValue

func (e *Example) GetValue() interface{}

GetValue returns example value.

func (*Example) Populate

func (e *Example) Populate(index int)

Populate populates example value.

type FileDoc

type FileDoc struct {
	// Name will be used in md file name pattern.
	Name string
	// Description file description, supports markdown.
	Description string
	// Structs structs defined in the file.
	Structs []*Doc
	Anchors map[string]string
	// contains filtered or unexported fields
}

FileDoc represents a single go file documentation.

func (*FileDoc) Encode

func (fd *FileDoc) Encode() ([]byte, error)

Encode encodes file documentation as MD file.

func (*FileDoc) Write

func (fd *FileDoc) Write(path, frontmatter string) error

Write dumps documentation string to folder.

type Option

type Option func(*Options)

Option gives ability to alter config encoder output settings.

func WithComments

func WithComments(flags CommentsFlags) Option

WithComments enables comments and examples in the encoder.

type Options

type Options struct {
	Comments CommentsFlags
}

Options defines encoder config.