lang

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Jun 17, 2023 License: MIT Imports: 20 Imported by: 7

README

lang

import "github.com/princjef/gomarkdoc/lang"

Package lang provides constructs for defining golang language constructs and extracting information from them for documentation purposes.

Index

func PackageSymbols

func PackageSymbols(pkg *doc.Package) map[string]Symbol

PackageSymbols gets the list of symbols for a doc package.

type Block

Block defines a single block element (e.g. paragraph, code block) in the documentation for a symbol or package.

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

func NewBlock
func NewBlock(cfg *Config, kind BlockKind, spans []*Span, inline bool) *Block

NewBlock creates a new block element of the provided kind and with the given text spans and a flag indicating whether this block is part of an inline element.

func NewListBlock
func NewListBlock(cfg *Config, list *List, inline bool) *Block

NewListBlock creates a new list block element and with the given list definition and a flag indicating whether this block is part of an inline element.

func ParseBlocks
func ParseBlocks(cfg *Config, blocks []comment.Block, inline bool) []*Block

ParseBlocks produces a set of blocks from the corresponding comment blocks. It also takes a flag indicating whether the blocks are part of an inline element such as a list item.

func (*Block) Inline
func (b *Block) Inline() bool

Inline indicates whether the block is part of an inline element, such as a list item.

func (*Block) Kind
func (b *Block) Kind() BlockKind

Kind provides the kind of data that this block's text should be interpreted as.

func (*Block) Level
func (b *Block) Level() int

Level provides the default level that a block of kind HeaderBlock will render at in the output. The level is not used for other block types.

func (*Block) List
func (b *Block) List() *List

List provides the list contents for a list block. Only relevant for blocks of type ListBlock.

func (*Block) Spans
func (b *Block) Spans() []*Span

Spans provides the raw text of the block's contents as a set of text spans. The text is pre-scrubbed and sanitized as determined by the block's Kind(), but it is not wrapped in any special constructs for rendering purposes (such as markdown code blocks).

type BlockKind

BlockKind identifies the type of block element represented by the corresponding Block.

type BlockKind string


const (
    // ParagraphBlock defines a block that represents a paragraph of text.
    ParagraphBlock BlockKind = "paragraph"

    // CodeBlock defines a block that represents a section of code.
    CodeBlock BlockKind = "code"

    // HeaderBlock defines a block that represents a section header.
    HeaderBlock BlockKind = "header"

    // ListBlock defines a block that represents an ordered or unordered list.
    ListBlock BlockKind = "list"
)

type Config

Config defines contextual information used to resolve documentation for a construct.

type Config struct {
    FileSet *token.FileSet
    Files   []*ast.File
    Level   int
    Repo    *Repo
    PkgDir  string
    WorkDir string
    Symbols map[string]Symbol
    Pkg     *doc.Package
    Log     logger.Logger
}

func NewConfig
func NewConfig(log logger.Logger, workDir string, pkgDir string, opts ...ConfigOption) (*Config, error)

NewConfig generates a Config for the provided package directory. It will resolve the filepath and attempt to determine the repository containing the directory. If no repository is found, the Repo field will be set to nil. An error is returned if the provided directory is invalid.

func (*Config) Inc
func (c *Config) Inc(step int) *Config

Inc copies the Config and increments the level by the provided step.

type ConfigOption

ConfigOption modifies the Config generated by NewConfig.

type ConfigOption func(c *Config) error

func ConfigWithRepoOverrides
func ConfigWithRepoOverrides(overrides *Repo) ConfigOption

ConfigWithRepoOverrides defines a set of manual overrides for the repository information to be used in place of automatic repository detection.

type Doc

Doc provides access to the documentation comment contents for a package or symbol in a structured form.

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

func NewDoc
func NewDoc(cfg *Config, text string) *Doc

NewDoc initializes a Doc struct from the provided raw documentation text and with headers rendered by default at the heading level provided. Documentation is separated into block level elements using the standard rules from golang's documentation conventions.

func (*Doc) Blocks
func (d *Doc) Blocks() []*Block

Blocks holds the list of block elements that makes up the documentation contents.

func (*Doc) Level
func (d *Doc) Level() int

Level provides the default level that headers within the documentation should be rendered

type Example

Example holds a single documentation example for a package or symbol.

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

func NewExample
func NewExample(cfg *Config, name string, doc *doc.Example) *Example

NewExample creates a new example from the example function's name, its documentation example and the files holding code related to the example.

func (*Example) Code
func (ex *Example) Code() (string, error)

Code provides the raw text code representation of the example's contents.

func (*Example) Doc
func (ex *Example) Doc() *Doc

Doc provides the structured contents of the documentation comment for the example.

func (*Example) HasOutput
func (ex *Example) HasOutput() bool

HasOutput indicates whether the example contains any example output.

func (*Example) Level
func (ex *Example) Level() int

Level provides the default level that headers for the example should be rendered.

func (*Example) Location
func (ex *Example) Location() Location

Location returns a representation of the node's location in a file within a repository.

func (*Example) Name
func (ex *Example) Name() string

Name provides a pretty-printed name for the specific example, if one was provided.

func (*Example) Output
func (ex *Example) Output() string

Output provides the code's example output.

func (*Example) Summary
func (ex *Example) Summary() string

Summary provides the one-sentence summary of the example's documentation comment.

func (*Example) Title
func (ex *Example) Title() string

Title provides a formatted string to print as the title of the example. It incorporates the example's name, if present.

type File

File holds information for rendering a single file that contains one or more packages.

type File struct {
    Header   string
    Footer   string
    Packages []*Package
}

func NewFile
func NewFile(header, footer string, packages []*Package) *File

NewFile creates a new instance of File with the provided information.

type Func

Func holds documentation information for a single func declaration within a package or type.

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

func NewFunc
func NewFunc(cfg *Config, doc *doc.Func, examples []*doc.Example) *Func

NewFunc creates a new Func from the corresponding documentation construct from the standard library, the related token.FileSet for the package and the list of examples for the package.

func (*Func) Anchor
func (fn *Func) Anchor() string

Anchor produces anchor text for the func.

func (*Func) Doc
func (fn *Func) Doc() *Doc

Doc provides the structured contents of the documentation comment for the function.

func (*Func) Examples
func (fn *Func) Examples() (examples []*Example)

Examples provides the list of examples from the list given on initialization that pertain to the function.

func (*Func) Level
func (fn *Func) Level() int

Level provides the default level at which headers for the func should be rendered in the final documentation.

func (*Func) Location
func (fn *Func) Location() Location

Location returns a representation of the node's location in a file within a repository.

func (*Func) Name
func (fn *Func) Name() string

Name provides the name of the function.

func (*Func) Receiver
func (fn *Func) Receiver() string

Receiver provides the type of the receiver for the function, or empty string if there is no receiver type.

func (*Func) Signature
func (fn *Func) Signature() (string, error)

Signature provides the raw text representation of the code for the function's signature.

func (*Func) Summary
func (fn *Func) Summary() string

Summary provides the one-sentence summary of the function's documentation comment

func (*Func) Title
func (fn *Func) Title() string

Title provides the formatted name of the func. It is primarily designed for generating headers.

type Item

Item defines a single item in a list in the documentation for a symbol or package.

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

func NewItem
func NewItem(cfg *Config, docItem *comment.ListItem) *Item

NewItem initializes a list item from the equivalent type from the comment package.

func (*Item) Blocks
func (i *Item) Blocks() []*Block

Blocks returns the blocks of documentation in a list item.

func (*Item) Kind
func (i *Item) Kind() ItemKind

Kind returns the kind of the list item.

func (*Item) Number
func (i *Item) Number() int

Number returns the number of the list item. Only populated if the item is of the OrderedItem kind.

type ItemKind

ItemKind identifies the kind of item

type ItemKind string


const (
    // OrderedItem identifies an ordered (i.e. numbered) item.
    OrderedItem ItemKind = "ordered"

    // UnorderedItem identifies an unordered (i.e. bulletted) item.
    UnorderedItem ItemKind = "unordered"
)

type List

List defines a list block element in the documentation for a symbol or package.

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

func NewList
func NewList(cfg *Config, docList *comment.List) *List

NewList initializes a list from the equivalent type from the comment package.

func (*List) BlankBetween
func (l *List) BlankBetween() bool

BlankBetween returns true if there should be a blank line between list items.

func (*List) Items
func (l *List) Items() []*Item

Items returns the slice of items in the list.

type Location

Location holds information for identifying a position within a file and repository, if present.

type Location struct {
    Start    Position
    End      Position
    Filepath string
    WorkDir  string
    Repo     *Repo
}

func NewLocation
func NewLocation(cfg *Config, node ast.Node) Location

NewLocation returns a location for the provided Config and ast.Node combination. This is typically not called directly, but is made available via the Location() methods of various lang constructs.

type Package

Package holds documentation information for a package and all of the symbols contained within it.

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

func NewPackage
func NewPackage(cfg *Config, examples []*doc.Example) *Package

NewPackage creates a representation of a package's documentation from the raw documentation constructs provided by the standard library. This is only recommended for advanced scenarios. Most consumers will find it easier to use NewPackageFromBuild instead.

func NewPackageFromBuild
func NewPackageFromBuild(log logger.Logger, pkg *build.Package, opts ...PackageOption) (*Package, error)

NewPackageFromBuild creates a representation of a package's documentation from the build metadata for that package. It can be configured using the provided options.

func (*Package) Consts
func (pkg *Package) Consts() (consts []*Value)

Consts lists the top-level constants provided by the package.

func (*Package) Dir
func (pkg *Package) Dir() string

Dir provides the name of the full directory in which the package is located.

func (*Package) Dirname
func (pkg *Package) Dirname() string

Dirname provides the name of the leaf directory in which the package is located.

func (*Package) Doc
func (pkg *Package) Doc() *Doc

Doc provides the structured contents of the documentation comment for the package.

func (*Package) Examples
func (pkg *Package) Examples() (examples []*Example)

Examples provides the package-level examples that have been defined. This does not include examples that are associated with symbols contained within the package.

func (*Package) Funcs
func (pkg *Package) Funcs() (funcs []*Func)

Funcs lists the top-level functions provided by the package.

func (*Package) Import
func (pkg *Package) Import() string

Import provides the raw text for the import declaration that is used to import code from the package. If your package's documentation is generated from a local path and does not use Go Modules, this will typically print `import "."`.

func (*Package) ImportPath
func (pkg *Package) ImportPath() string

ImportPath provides the identifier used for the package when installing or importing the package. If your package's documentation is generated from a local path and does not use Go Modules, this will typically print `.`.

func (*Package) Level
func (pkg *Package) Level() int

Level provides the default level that headers for the package's root documentation should be rendered.

func (*Package) Name
func (pkg *Package) Name() string

Name provides the name of the package as it would be seen from another package importing it.

func (*Package) Summary
func (pkg *Package) Summary() string

Summary provides the one-sentence summary of the package's documentation comment.

func (*Package) Types
func (pkg *Package) Types() (types []*Type)

Types lists the top-level types provided by the package.

func (*Package) Vars
func (pkg *Package) Vars() (vars []*Value)

Vars lists the top-level variables provided by the package.

type PackageOption

PackageOption configures one or more options for the package.

type PackageOption func(opts *PackageOptions) error

func PackageWithRepositoryOverrides
func PackageWithRepositoryOverrides(repo *Repo) PackageOption

PackageWithRepositoryOverrides can be used along with the NewPackageFromBuild function to define manual overrides to the automatic repository detection logic.

func PackageWithUnexportedIncluded
func PackageWithUnexportedIncluded() PackageOption

PackageWithUnexportedIncluded can be used along with the NewPackageFromBuild function to specify that all symbols, including unexported ones, should be included in the documentation for the package.

type PackageOptions

PackageOptions holds options related to the configuration of the package and its documentation on creation.

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

type Position

Position represents a line and column number within a file.

type Position struct {
    Line int
    Col  int
}

type Repo

Repo represents information about a repository relevant to documentation generation.

type Repo struct {
    Remote        string
    DefaultBranch string
    PathFromRoot  string
}

type Span

Span defines a single text span in a block for documentation of a symbol or package.

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

func NewSpan
func NewSpan(cfg *Config, kind SpanKind, text string, url string) *Span

NewSpan creates a new span.

func ParseSpans
func ParseSpans(cfg *Config, texts []comment.Text) []*Span

ParseSpans turns a set of *comment.Text entries into a slice of spans.

func (*Span) Kind
func (s *Span) Kind() SpanKind

Kind provides the kind of data that this span represents.

func (*Span) Text
func (s *Span) Text() string

Text provides the raw text for the span.

func (*Span) URL
func (s *Span) URL() string

URL provides the url associated with the span, if any.

type SpanKind

SpanKind identifies the type of span element represented by the corresponding Span.

type SpanKind string


const (
    // TextSpan defines a span that represents plain text.
    TextSpan SpanKind = "text"

    // RawTextSpan defines a span that represents plain text that should be
    // displayed as-is.
    RawTextSpan SpanKind = "rawText"

    // LinkSpan defines a span that represents a link.
    LinkSpan SpanKind = "link"

    // AutolinkSpan defines a span that represents text which is itself a link.
    AutolinkSpan SpanKind = "autolink"
)

type Symbol

Symbol provides identity information for a symbol in a package.

type Symbol struct {
    // Receiver holds the receiver for a method or field.
    Receiver string
    // Name holds the name of the symbol itself.
    Name string
    // Kind identifies the category of the symbol.
    Kind SymbolKind
    // Parent holds the linkable parent symbol which contains this one.
    Parent *Symbol
}

func (Symbol) Anchor
func (s Symbol) Anchor() string

Anchor produces anchor text for the symbol.

type SymbolKind

SymbolKind identifies the type of symbol.

type SymbolKind int

The list of valid symbol kinds.

const (
    TypeSymbolKind SymbolKind = iota + 1
    FuncSymbolKind
    ConstSymbolKind
    VarSymbolKind
    MethodSymbolKind
    FieldSymbolKind
)

type Type

Type holds documentation information for a type declaration.

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

func NewType
func NewType(cfg *Config, doc *doc.Type, examples []*doc.Example) *Type

NewType creates a Type from the raw documentation representation of the type, the token.FileSet for the package's files and the full list of examples from the containing package.

func (*Type) Anchor
func (typ *Type) Anchor() string

Anchor produces anchor text for the type.

func (*Type) Consts
func (typ *Type) Consts() []*Value

Consts lists the const declaration blocks containing values of this type.

func (*Type) Decl
func (typ *Type) Decl() (string, error)

Decl provides the raw text representation of the code for the type's declaration.

func (*Type) Doc
func (typ *Type) Doc() *Doc

Doc provides the structured contents of the documentation comment for the type.

func (*Type) Examples
func (typ *Type) Examples() (examples []*Example)

Examples lists the examples pertaining to the type from the set provided on initialization.

func (*Type) Funcs
func (typ *Type) Funcs() []*Func

Funcs lists the funcs related to the type. This only includes functions which return an instance of the type or its pointer.

func (*Type) Level
func (typ *Type) Level() int

Level provides the default level that headers for the type should be rendered.

func (*Type) Location
func (typ *Type) Location() Location

Location returns a representation of the node's location in a file within a repository.

func (*Type) Methods
func (typ *Type) Methods() []*Func

Methods lists the funcs that use the type as a value or pointer receiver.

func (*Type) Name
func (typ *Type) Name() string

Name provides the name of the type

func (*Type) Summary
func (typ *Type) Summary() string

Summary provides the one-sentence summary of the type's documentation comment.

func (*Type) Title
func (typ *Type) Title() string

Title provides a formatted name suitable for use in a header identifying the type.

func (*Type) Vars
func (typ *Type) Vars() []*Value

Vars lists the var declaration blocks containing values of this type.

type Value

Value holds documentation for a var or const declaration within a package.

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

func NewValue
func NewValue(cfg *Config, doc *doc.Value) *Value

NewValue creates a new Value from the raw const or var documentation and the token.FileSet of files for the containing package.

func (*Value) Anchor
func (v *Value) Anchor() string

Anchor produces anchor text for the value.

func (*Value) Decl
func (v *Value) Decl() (string, error)

Decl provides the raw text representation of the code for declaring the const or var.

func (*Value) Doc
func (v *Value) Doc() *Doc

Doc provides the structured contents of the documentation comment for the example.

func (*Value) Level
func (v *Value) Level() int

Level provides the default level that headers for the value should be rendered.

func (*Value) Location
func (v *Value) Location() Location

Location returns a representation of the node's location in a file within a repository.

func (*Value) Summary
func (v *Value) Summary() string

Summary provides the one-sentence summary of the value's documentation comment.

Generated by gomarkdoc

Documentation

Overview

Package lang provides constructs for defining golang language constructs and extracting information from them for documentation purposes.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func PackageSymbols added in v1.0.0 

func PackageSymbols(pkg *doc.Package) map[string]Symbol

PackageSymbols gets the list of symbols for a doc package.

Types

type Block 

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

Block defines a single block element (e.g. paragraph, code block) in the documentation for a symbol or package.

func NewBlock 

func NewBlock(cfg *Config, kind BlockKind, spans []*Span, inline bool) *Block

NewBlock creates a new block element of the provided kind and with the given text spans and a flag indicating whether this block is part of an inline element.

func NewListBlock added in v1.0.0 

func NewListBlock(cfg *Config, list *List, inline bool) *Block

NewListBlock creates a new list block element and with the given list definition and a flag indicating whether this block is part of an inline element.

func ParseBlocks added in v1.0.0 

func ParseBlocks(cfg *Config, blocks []comment.Block, inline bool) []*Block

ParseBlocks produces a set of blocks from the corresponding comment blocks. It also takes a flag indicating whether the blocks are part of an inline element such as a list item.

func (*Block) Inline added in v1.0.0 

func (b *Block) Inline() bool

Inline indicates whether the block is part of an inline element, such as a list item.

func (*Block) Kind 

func (b *Block) Kind() BlockKind

Kind provides the kind of data that this block's text should be interpreted as.

func (*Block) Level 

func (b *Block) Level() int

Level provides the default level that a block of kind HeaderBlock will render at in the output. The level is not used for other block types.

func (*Block) List added in v1.0.0 

func (b *Block) List() *List

List provides the list contents for a list block. Only relevant for blocks of type ListBlock.

func (*Block) Spans added in v1.0.0 

func (b *Block) Spans() []*Span

Spans provides the raw text of the block's contents as a set of text spans. The text is pre-scrubbed and sanitized as determined by the block's Kind(), but it is not wrapped in any special constructs for rendering purposes (such as markdown code blocks).

type BlockKind 

type BlockKind string

BlockKind identifies the type of block element represented by the corresponding Block. 

const (
	// ParagraphBlock defines a block that represents a paragraph of text.
	ParagraphBlock BlockKind = "paragraph"

	// CodeBlock defines a block that represents a section of code.
	CodeBlock BlockKind = "code"

	// HeaderBlock defines a block that represents a section header.
	HeaderBlock BlockKind = "header"

	// ListBlock defines a block that represents an ordered or unordered list.
	ListBlock BlockKind = "list"
)

type Config 

type Config struct {
	FileSet *token.FileSet
	Files   []*ast.File
	Level   int
	Repo    *Repo
	PkgDir  string
	WorkDir string
	Symbols map[string]Symbol
	Pkg     *doc.Package
	Log     logger.Logger
}

Config defines contextual information used to resolve documentation for a construct.

func NewConfig 

func NewConfig(log logger.Logger, workDir string, pkgDir string, opts ...ConfigOption) (*Config, error)

NewConfig generates a Config for the provided package directory. It will resolve the filepath and attempt to determine the repository containing the directory. If no repository is found, the Repo field will be set to nil. An error is returned if the provided directory is invalid.

func (*Config) Inc 

func (c *Config) Inc(step int) *Config

Inc copies the Config and increments the level by the provided step.

type ConfigOption 

type ConfigOption func(c *Config) error

ConfigOption modifies the Config generated by NewConfig.

func ConfigWithRepoOverrides 

func ConfigWithRepoOverrides(overrides *Repo) ConfigOption

ConfigWithRepoOverrides defines a set of manual overrides for the repository information to be used in place of automatic repository detection.

type Doc 

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

Doc provides access to the documentation comment contents for a package or symbol in a structured form.

func NewDoc 

func NewDoc(cfg *Config, text string) *Doc

NewDoc initializes a Doc struct from the provided raw documentation text and with headers rendered by default at the heading level provided. Documentation is separated into block level elements using the standard rules from golang's documentation conventions.

func (*Doc) Blocks 

func (d *Doc) Blocks() []*Block

Blocks holds the list of block elements that makes up the documentation contents.

func (*Doc) Level 

func (d *Doc) Level() int

Level provides the default level that headers within the documentation should be rendered

type Example 

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

Example holds a single documentation example for a package or symbol.

func NewExample 

func NewExample(cfg *Config, name string, doc *doc.Example) *Example

NewExample creates a new example from the example function's name, its documentation example and the files holding code related to the example.

func (*Example) Code 

func (ex *Example) Code() (string, error)

Code provides the raw text code representation of the example's contents.

func (*Example) Doc 

func (ex *Example) Doc() *Doc

Doc provides the structured contents of the documentation comment for the example.

func (*Example) HasOutput added in v0.1.2 

func (ex *Example) HasOutput() bool

HasOutput indicates whether the example contains any example output.

func (*Example) Level 

func (ex *Example) Level() int

Level provides the default level that headers for the example should be rendered.

func (*Example) Location 

func (ex *Example) Location() Location

Location returns a representation of the node's location in a file within a repository.

func (*Example) Name 

func (ex *Example) Name() string

Name provides a pretty-printed name for the specific example, if one was provided.

func (*Example) Output added in v0.1.2 

func (ex *Example) Output() string

Output provides the code's example output.

func (*Example) Summary 

func (ex *Example) Summary() string

Summary provides the one-sentence summary of the example's documentation comment.

func (*Example) Title 

func (ex *Example) Title() string

Title provides a formatted string to print as the title of the example. It incorporates the example's name, if present.

type File 

type File struct {
	Header   string
	Footer   string
	Packages []*Package
}

File holds information for rendering a single file that contains one or more packages.

func NewFile 

func NewFile(header, footer string, packages []*Package) *File

NewFile creates a new instance of File with the provided information.

type Func 

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

Func holds documentation information for a single func declaration within a package or type.

func NewFunc 

func NewFunc(cfg *Config, doc *doc.Func, examples []*doc.Example) *Func

NewFunc creates a new Func from the corresponding documentation construct from the standard library, the related token.FileSet for the package and the list of examples for the package.

func (*Func) Anchor added in v1.0.0 

func (fn *Func) Anchor() string

Anchor produces anchor text for the func.

func (*Func) Doc 

func (fn *Func) Doc() *Doc

Doc provides the structured contents of the documentation comment for the function.

func (*Func) Examples 

func (fn *Func) Examples() (examples []*Example)

Examples provides the list of examples from the list given on initialization that pertain to the function.

func (*Func) Level 

func (fn *Func) Level() int

Level provides the default level at which headers for the func should be rendered in the final documentation.

func (*Func) Location 

func (fn *Func) Location() Location

Location returns a representation of the node's location in a file within a repository.

func (*Func) Name 

func (fn *Func) Name() string

Name provides the name of the function.

func (*Func) Receiver 

func (fn *Func) Receiver() string

Receiver provides the type of the receiver for the function, or empty string if there is no receiver type.

func (*Func) Signature 

func (fn *Func) Signature() (string, error)

Signature provides the raw text representation of the code for the function's signature.

func (*Func) Summary 

func (fn *Func) Summary() string

Summary provides the one-sentence summary of the function's documentation comment

func (*Func) Title 

func (fn *Func) Title() string

Title provides the formatted name of the func. It is primarily designed for generating headers.

type Item added in v1.0.0 

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

Item defines a single item in a list in the documentation for a symbol or package.

func NewItem added in v1.0.0 

func NewItem(cfg *Config, docItem *comment.ListItem) *Item

NewItem initializes a list item from the equivalent type from the comment package.

func (*Item) Blocks added in v1.0.0 

func (i *Item) Blocks() []*Block

Blocks returns the blocks of documentation in a list item.

func (*Item) Kind added in v1.0.0 

func (i *Item) Kind() ItemKind

Kind returns the kind of the list item.

func (*Item) Number added in v1.0.0 

func (i *Item) Number() int

Number returns the number of the list item. Only populated if the item is of the OrderedItem kind.

type ItemKind added in v1.0.0 

type ItemKind string

ItemKind identifies the kind of item 

const (
	// OrderedItem identifies an ordered (i.e. numbered) item.
	OrderedItem ItemKind = "ordered"

	// UnorderedItem identifies an unordered (i.e. bulletted) item.
	UnorderedItem ItemKind = "unordered"
)

type List added in v1.0.0 

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

List defines a list block element in the documentation for a symbol or package.

func NewList added in v1.0.0 

func NewList(cfg *Config, docList *comment.List) *List

NewList initializes a list from the equivalent type from the comment package.

func (*List) BlankBetween added in v1.0.0 

func (l *List) BlankBetween() bool

BlankBetween returns true if there should be a blank line between list items.

func (*List) Items added in v1.0.0 

func (l *List) Items() []*Item

Items returns the slice of items in the list.

type Location 

type Location struct {
	Start    Position
	End      Position
	Filepath string
	WorkDir  string
	Repo     *Repo
}

Location holds information for identifying a position within a file and repository, if present.

func NewLocation 

func NewLocation(cfg *Config, node ast.Node) Location

NewLocation returns a location for the provided Config and ast.Node combination. This is typically not called directly, but is made available via the Location() methods of various lang constructs.

type Package 

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

Package holds documentation information for a package and all of the symbols contained within it.

func NewPackage 

func NewPackage(cfg *Config, examples []*doc.Example) *Package

NewPackage creates a representation of a package's documentation from the raw documentation constructs provided by the standard library. This is only recommended for advanced scenarios. Most consumers will find it easier to use NewPackageFromBuild instead.

func NewPackageFromBuild 

func NewPackageFromBuild(log logger.Logger, pkg *build.Package, opts ...PackageOption) (*Package, error)

NewPackageFromBuild creates a representation of a package's documentation from the build metadata for that package. It can be configured using the provided options.

func (*Package) Consts 

func (pkg *Package) Consts() (consts []*Value)

Consts lists the top-level constants provided by the package.

func (*Package) Dir 

func (pkg *Package) Dir() string

Dir provides the name of the full directory in which the package is located.

func (*Package) Dirname 

func (pkg *Package) Dirname() string

Dirname provides the name of the leaf directory in which the package is located.

func (*Package) Doc 

func (pkg *Package) Doc() *Doc

Doc provides the structured contents of the documentation comment for the package.

func (*Package) Examples 

func (pkg *Package) Examples() (examples []*Example)

Examples provides the package-level examples that have been defined. This does not include examples that are associated with symbols contained within the package.

func (*Package) Funcs 

func (pkg *Package) Funcs() (funcs []*Func)

Funcs lists the top-level functions provided by the package.

func (*Package) Import 

func (pkg *Package) Import() string

Import provides the raw text for the import declaration that is used to import code from the package. If your package's documentation is generated from a local path and does not use Go Modules, this will typically print `import "."`.

func (*Package) ImportPath added in v0.4.0 

func (pkg *Package) ImportPath() string

ImportPath provides the identifier used for the package when installing or importing the package. If your package's documentation is generated from a local path and does not use Go Modules, this will typically print `.`.

func (*Package) Level 

func (pkg *Package) Level() int

Level provides the default level that headers for the package's root documentation should be rendered.

func (*Package) Name 

func (pkg *Package) Name() string

Name provides the name of the package as it would be seen from another package importing it.

func (*Package) Summary 

func (pkg *Package) Summary() string

Summary provides the one-sentence summary of the package's documentation comment.

func (*Package) Types 

func (pkg *Package) Types() (types []*Type)

Types lists the top-level types provided by the package.

func (*Package) Vars 

func (pkg *Package) Vars() (vars []*Value)

Vars lists the top-level variables provided by the package.

type PackageOption 

type PackageOption func(opts *PackageOptions) error

PackageOption configures one or more options for the package.

func PackageWithRepositoryOverrides 

func PackageWithRepositoryOverrides(repo *Repo) PackageOption

PackageWithRepositoryOverrides can be used along with the NewPackageFromBuild function to define manual overrides to the automatic repository detection logic.

func PackageWithUnexportedIncluded 

func PackageWithUnexportedIncluded() PackageOption

PackageWithUnexportedIncluded can be used along with the NewPackageFromBuild function to specify that all symbols, including unexported ones, should be included in the documentation for the package.

type PackageOptions 

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

PackageOptions holds options related to the configuration of the package and its documentation on creation.

type Position 

type Position struct {
	Line int
	Col  int
}

Position represents a line and column number within a file.

type Repo 

type Repo struct {
	Remote        string
	DefaultBranch string
	PathFromRoot  string
}

Repo represents information about a repository relevant to documentation generation.

type Span added in v1.0.0 

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

Span defines a single text span in a block for documentation of a symbol or package.

func NewSpan added in v1.0.0 

func NewSpan(cfg *Config, kind SpanKind, text string, url string) *Span

NewSpan creates a new span.

func ParseSpans added in v1.0.0 

func ParseSpans(cfg *Config, texts []comment.Text) []*Span

ParseSpans turns a set of *comment.Text entries into a slice of spans.

func (*Span) Kind added in v1.0.0 

func (s *Span) Kind() SpanKind

Kind provides the kind of data that this span represents.

func (*Span) Text added in v1.0.0 

func (s *Span) Text() string

Text provides the raw text for the span.

func (*Span) URL added in v1.0.0 

func (s *Span) URL() string

URL provides the url associated with the span, if any.

type SpanKind added in v1.0.0 

type SpanKind string

SpanKind identifies the type of span element represented by the corresponding Span. 

const (
	// TextSpan defines a span that represents plain text.
	TextSpan SpanKind = "text"

	// RawTextSpan defines a span that represents plain text that should be
	// displayed as-is.
	RawTextSpan SpanKind = "rawText"

	// LinkSpan defines a span that represents a link.
	LinkSpan SpanKind = "link"

	// AutolinkSpan defines a span that represents text which is itself a link.
	AutolinkSpan SpanKind = "autolink"
)

type Symbol added in v1.0.0 

type Symbol struct {
	// Receiver holds the receiver for a method or field.
	Receiver string
	// Name holds the name of the symbol itself.
	Name string
	// Kind identifies the category of the symbol.
	Kind SymbolKind
	// Parent holds the linkable parent symbol which contains this one.
	Parent *Symbol
}

Symbol provides identity information for a symbol in a package.

func (Symbol) Anchor added in v1.0.0 

func (s Symbol) Anchor() string

Anchor produces anchor text for the symbol.

type SymbolKind added in v1.0.0 

type SymbolKind int

SymbolKind identifies the type of symbol. 

const (
	TypeSymbolKind SymbolKind = iota + 1
	FuncSymbolKind
	ConstSymbolKind
	VarSymbolKind
	MethodSymbolKind
	FieldSymbolKind
)

The list of valid symbol kinds.

type Type 

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

Type holds documentation information for a type declaration.

func NewType 

func NewType(cfg *Config, doc *doc.Type, examples []*doc.Example) *Type

NewType creates a Type from the raw documentation representation of the type, the token.FileSet for the package's files and the full list of examples from the containing package.

func (*Type) Anchor added in v1.0.0 

func (typ *Type) Anchor() string

Anchor produces anchor text for the type.

func (*Type) Consts 

func (typ *Type) Consts() []*Value

Consts lists the const declaration blocks containing values of this type.

func (*Type) Decl 

func (typ *Type) Decl() (string, error)

Decl provides the raw text representation of the code for the type's declaration.

func (*Type) Doc 

func (typ *Type) Doc() *Doc

Doc provides the structured contents of the documentation comment for the type.

func (*Type) Examples 

func (typ *Type) Examples() (examples []*Example)

Examples lists the examples pertaining to the type from the set provided on initialization.

func (*Type) Funcs 

func (typ *Type) Funcs() []*Func

Funcs lists the funcs related to the type. This only includes functions which return an instance of the type or its pointer.

func (*Type) Level 

func (typ *Type) Level() int

Level provides the default level that headers for the type should be rendered.

func (*Type) Location 

func (typ *Type) Location() Location

Location returns a representation of the node's location in a file within a repository.

func (*Type) Methods 

func (typ *Type) Methods() []*Func

Methods lists the funcs that use the type as a value or pointer receiver.

func (*Type) Name 

func (typ *Type) Name() string

Name provides the name of the type

func (*Type) Summary 

func (typ *Type) Summary() string

Summary provides the one-sentence summary of the type's documentation comment.

func (*Type) Title 

func (typ *Type) Title() string

Title provides a formatted name suitable for use in a header identifying the type.

func (*Type) Vars 

func (typ *Type) Vars() []*Value

Vars lists the var declaration blocks containing values of this type.

type Value 

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

Value holds documentation for a var or const declaration within a package.

func NewValue 

func NewValue(cfg *Config, doc *doc.Value) *Value

NewValue creates a new Value from the raw const or var documentation and the token.FileSet of files for the containing package.

func (*Value) Anchor added in v1.0.0 

func (v *Value) Anchor() string

Anchor produces anchor text for the value.

func (*Value) Decl 

func (v *Value) Decl() (string, error)

Decl provides the raw text representation of the code for declaring the const or var.

func (*Value) Doc 

func (v *Value) Doc() *Doc

Doc provides the structured contents of the documentation comment for the example.

func (*Value) Level 

func (v *Value) Level() int

Level provides the default level that headers for the value should be rendered.

func (*Value) Location 

func (v *Value) Location() Location

Location returns a representation of the node's location in a file within a repository.

func (*Value) Summary 

func (v *Value) Summary() string

Summary provides the one-sentence summary of the value's documentation comment.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.