encoder

Documentation

Index

• Constants
• type Appearance
• type CommentsFlags
• type Doc
  • func (d *Doc) AddExample(name string, value any)
  • func (d *Doc) Describe(field string, short bool) string
  • func (d *Doc) Field(i int) *Doc
• type Documented
• type Encoder
  • func NewEncoder(value any, opts ...Option) *Encoder
  • func (e *Encoder) Encode() ([]byte, error)
  • func (e *Encoder) Marshal() (*yaml.Node, error)
• type Example
  • func (e *Example) GetValue() any
  • func (e *Example) Populate(index int)
• type FileDoc
  • func (fd *FileDoc) Encode(root *Doc, frontmatter func(title, description string) string) ([]byte, error)
  • func (fd *FileDoc) Write(path string, frontmatter func(title, description string) string) error
• type Option
  • func WithComments(flags CommentsFlags) Option
  • func WithOmitEmpty(value bool) 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 any)

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 any, 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() any

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
	// Types is map of all non-trivial types defined in the file.
	Types map[string]*Doc
}

FileDoc represents a single go file documentation.

func (*FileDoc) Encode

func (fd *FileDoc) Encode(root *Doc, frontmatter func(title, description string) string) ([]byte, error)

Encode encodes file documentation as MD file.

func (*FileDoc) Write

func (fd *FileDoc) Write(path string, frontmatter func(title, description string) 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.

func WithOmitEmpty

func WithOmitEmpty(value bool) Option

WithOmitEmpty toggles omitempty handling.

type Options

type Options struct {
	Comments  CommentsFlags
	OmitEmpty bool
}

Options defines encoder config.