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

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

• type Block
  • func NewBlock(cfg *Config, kind BlockKind, text string) *Block
  • func (b *Block) Kind() BlockKind
  • func (b *Block) Level() int
  • func (b *Block) Text() string
• type BlockKind
• type Config
  • func NewConfig(log logger.Logger, workDir string, pkgDir string, opts ...ConfigOption) (*Config, error)
  • func (c *Config) Inc(step int) *Config
• type ConfigOption
  • func ConfigWithRepoOverrides(overrides *Repo) ConfigOption
• type Doc
  • func NewDoc(cfg *Config, text string) *Doc
  • func (d *Doc) Blocks() []*Block
  • func (d *Doc) Level() int
• type Example
  • func NewExample(cfg *Config, name string, doc *doc.Example) *Example
  • func (ex *Example) Code() (string, error)
  • func (ex *Example) Doc() *Doc
  • func (ex *Example) HasOutput() bool
  • func (ex *Example) Level() int
  • func (ex *Example) Location() Location
  • func (ex *Example) Name() string
  • func (ex *Example) Output() string
  • func (ex *Example) Summary() string
  • func (ex *Example) Title() string
• type File
  • func NewFile(header, footer string, packages []*Package) *File
• type Func
  • func NewFunc(cfg *Config, doc *doc.Func, examples []*doc.Example) *Func
  • func (fn *Func) Doc() *Doc
  • func (fn *Func) Examples() (examples []*Example)
  • func (fn *Func) Level() int
  • func (fn *Func) Location() Location
  • func (fn *Func) Name() string
  • func (fn *Func) Receiver() string
  • func (fn *Func) Signature() (string, error)
  • func (fn *Func) Summary() string
  • func (fn *Func) Title() string
• type Location
  • func NewLocation(cfg *Config, node ast.Node) Location
• type Package
  • func NewPackage(cfg *Config, doc *doc.Package, examples []*doc.Example) *Package
  • func NewPackageFromBuild(log logger.Logger, pkg *build.Package, opts ...PackageOption) (*Package, error)
  • func (pkg *Package) Consts() (consts []*Value)
  • func (pkg *Package) Dir() string
  • func (pkg *Package) Dirname() string
  • func (pkg *Package) Doc() *Doc
  • func (pkg *Package) Examples() (examples []*Example)
  • func (pkg *Package) Funcs() (funcs []*Func)
  • func (pkg *Package) Import() string
  • func (pkg *Package) Level() int
  • func (pkg *Package) Name() string
  • func (pkg *Package) Summary() string
  • func (pkg *Package) Types() (types []*Type)
  • func (pkg *Package) Vars() (vars []*Value)
• type PackageOption
  • func PackageWithRepositoryOverrides(repo *Repo) PackageOption
  • func PackageWithUnexportedIncluded() PackageOption
• type PackageOptions
• type Position
• type Repo
• type Type
  • func NewType(cfg *Config, doc *doc.Type, examples []*doc.Example) *Type
  • func (typ *Type) Consts() []*Value
  • func (typ *Type) Decl() (string, error)
  • func (typ *Type) Doc() *Doc
  • func (typ *Type) Examples() (examples []*Example)
  • func (typ *Type) Funcs() []*Func
  • func (typ *Type) Level() int
  • func (typ *Type) Location() Location
  • func (typ *Type) Methods() []*Func
  • func (typ *Type) Name() string
  • func (typ *Type) Summary() string
  • func (typ *Type) Title() string
  • func (typ *Type) Vars() []*Value
• type Value
  • func NewValue(cfg *Config, doc *doc.Value) *Value
  • func (v *Value) Decl() (string, error)
  • func (v *Value) Doc() *Doc
  • func (v *Value) Level() int
  • func (v *Value) Location() Location
  • func (v *Value) Summary() string

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(cfg *Config, kind BlockKind, text string) *Block

NewBlock creates a new block element of the provided kind and with the given text contents.

func (b *Block) Kind() BlockKind

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

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 (b *Block) Text() string

Text provides the raw text of the block's contents. 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).

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

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

type Config struct {
    FileSet *token.FileSet
    Level   int
    Repo    *Repo
    PkgDir  string
    WorkDir string
    Log     logger.Logger
}

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 (c *Config) Inc(step int) *Config

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

ConfigOption modifies the Config generated by NewConfig.

type ConfigOption func(c *Config) error

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.

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(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 (d *Doc) Blocks() []*Block

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

func (d *Doc) Level() int

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

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

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

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 (ex *Example) Code() (string, error)

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

func (ex *Example) Doc() *Doc

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

func (ex *Example) HasOutput() bool

HasOutput indicates whether the example contains any example output.

func (ex *Example) Level() int

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

func (ex *Example) Location() Location

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

func (ex *Example) Name() string

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

func (ex *Example) Output() string

Output provides the code's example output.

func (ex *Example) Summary() string

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

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.

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(header, footer string, packages []*Package) *File

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

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

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

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 (fn *Func) Doc() *Doc

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

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

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

func (fn *Func) Level() int

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

func (fn *Func) Location() Location

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

func (fn *Func) Name() string

Name provides the name of the function.

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 (fn *Func) Signature() (string, error)

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

func (fn *Func) Summary() string

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

func (fn *Func) Title() string

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

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

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(cfg *Config, doc *doc.Package, 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(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 (pkg *Package) Consts() (consts []*Value)

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

func (pkg *Package) Dir() string

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

func (pkg *Package) Dirname() string

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

func (pkg *Package) Doc() *Doc

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

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 (pkg *Package) Funcs() (funcs []*Func)

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

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 (pkg *Package) Level() int

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

func (pkg *Package) Name() string

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

func (pkg *Package) Summary() string

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

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

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

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

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

PackageOption configures one or more options for the package.

type PackageOption func(opts *PackageOptions) error

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

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

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

Position represents a line and column number within a file.

type Position struct {
    Line int
    Col  int
}

Repo represents information about a repository relevant to documentation generation.

type Repo struct {
    Remote        string
    DefaultBranch string
    PathFromRoot  string
}

Type holds documentation information for a type declaration.

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

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 (typ *Type) Consts() []*Value

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

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

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

func (typ *Type) Doc() *Doc

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

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

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

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 (typ *Type) Level() int

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

func (typ *Type) Location() Location

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

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

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

func (typ *Type) Name() string

Name provides the name of the type

func (typ *Type) Summary() string

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

func (typ *Type) Title() string

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

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

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

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

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

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 (v *Value) Decl() (string, error)

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

func (v *Value) Doc() *Doc

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

func (v *Value) Level() int

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

func (v *Value) Location() Location

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

func (v *Value) Summary() string

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

Generated by gomarkdoc