luci: go.chromium.org/luci/lucicfg/docgen/ast Index | Files

package ast

import "go.chromium.org/luci/lucicfg/docgen/ast"

Package ast defines AST relevant for the documentation generation.

It recognizes top-level function declarations, top-level assignments (e.g. for constants and aliases), load(...) statements (to follow imported symbols), and struct(...) declarations.

Index

Package Files

parser.go

type Ellipsis Uses

type Ellipsis string

Ellipsis represents a complex expression that we don't care about.

A value of Ellipsis type is usually literally just "...".

type EnumerableNode Uses

type EnumerableNode interface {
    Node

    // EnumNodes returns a list of subnodes. It should not be mutated.
    EnumNodes() []Node
}

EnumerableNode is a node that has a variable number of subnodes.

Used to represents structs, modules and invocations.

type ExternalReference Uses

type ExternalReference struct {
    ExternalName string // name of the symbol in the loaded module
    Module       string // path of the loaded module
    // contains filtered or unexported fields
}

ExternalReference is a node that represents a symbol imported though load(...) statement.

For load statement load("file.star", x="y") we get an ExternalReference with name "x", ExternalName "y" and Module "file.star".

func (*ExternalReference) Comments Uses

func (b *ExternalReference) Comments() string

func (*ExternalReference) Doc Uses

func (b *ExternalReference) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*ExternalReference) Name Uses

func (b *ExternalReference) Name() string

func (*ExternalReference) Span Uses

func (b *ExternalReference) Span() (syntax.Position, syntax.Position)

type Function Uses

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

Function is a node that represents a function definition.

func (*Function) Comments Uses

func (b *Function) Comments() string

func (*Function) Doc Uses

func (n *Function) Doc() string

Doc extracts the documentation from the docstring.

func (*Function) Name Uses

func (b *Function) Name() string

func (*Function) Span Uses

func (b *Function) Span() (syntax.Position, syntax.Position)

type Invocation Uses

type Invocation struct {
    Func []string // e.g. ["ns1, "ns2", "func"]
    Args []Node   // keyword arguments in order of their definition
    // contains filtered or unexported fields
}

Invocation represents `<name> = ns1.ns2.func(arg1=..., arg2=...)` call. Only keyword arguments are recognized.

func (*Invocation) Comments Uses

func (b *Invocation) Comments() string

func (*Invocation) Doc Uses

func (b *Invocation) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*Invocation) EnumNodes Uses

func (inv *Invocation) EnumNodes() []Node

EnumNodes returns list of nodes that represent arguments.

func (*Invocation) Name Uses

func (b *Invocation) Name() string

func (*Invocation) Span Uses

func (b *Invocation) Span() (syntax.Position, syntax.Position)

type Module Uses

type Module struct {
    Namespace // all top-level symbols
    // contains filtered or unexported fields
}

Module is a parsed Starlark file.

func ParseModule Uses

func ParseModule(filename, body string) (*Module, error)

ParseModule parses a single Starlark module.

Filename is only used when recording position information.

func (*Module) Comments Uses

func (b *Module) Comments() string

func (*Module) Doc Uses

func (n *Module) Doc() string

Doc extracts the documentation from the docstring.

func (*Module) Name Uses

func (b *Module) Name() string

func (*Module) Span Uses

func (b *Module) Span() (syntax.Position, syntax.Position)

type Namespace Uses

type Namespace struct {
    Nodes []Node // nodes defined in the namespace, in order they were defined
    // contains filtered or unexported fields
}

Namespace is a node that contains a bunch of definitions grouped together.

Examples of namespaces are top-level module dicts and structs.

func (*Namespace) Comments Uses

func (b *Namespace) Comments() string

func (*Namespace) Doc Uses

func (b *Namespace) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*Namespace) EnumNodes Uses

func (ns *Namespace) EnumNodes() []Node

EnumNodes returns list of nodes that represent definitions in the namespace.

func (*Namespace) Name Uses

func (b *Namespace) Name() string

func (*Namespace) Span Uses

func (b *Namespace) Span() (syntax.Position, syntax.Position)

type Node Uses

type Node interface {
    // Name is the name of the entity this node defines.
    //
    // E.g. it's the name of a function, variable, constant, etc.
    //
    // It may be a "private" name. Many definitions are defined using their
    // private names first, and then exposed publicly via separate definition
    // (such definitions are represented by Reference or ExternalReference nodes).
    Name() string

    // Span is where this node was defined in the original starlark code.
    Span() (start syntax.Position, end syntax.Position)

    // Comments is a comment block immediately preceding the definition.
    Comments() string

    // Doc is a documentation string for this symbol extracted either from a
    // docstring or from comments.
    Doc() string
    // contains filtered or unexported methods
}

Node is a documentation-relevant declaration of something in a file.

Nodes form a tree. This tree is a reduction of a full AST of the starlark file to a form we care about when generating the documentation.

The top of the tree is represented by a Module node.

type Reference Uses

type Reference struct {
    Path []string // the ref path on the right hand side, e.g. ['a', 'b', 'c'].
    // contains filtered or unexported fields
}

Reference is a node that represents <var> = a.b.c.

It is either a top-level assignment, or a keyword argument in a function call (e.g. when defining struct(...)).

func (*Reference) Comments Uses

func (b *Reference) Comments() string

func (*Reference) Doc Uses

func (b *Reference) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*Reference) Name Uses

func (b *Reference) Name() string

func (*Reference) Span Uses

func (b *Reference) Span() (syntax.Position, syntax.Position)

type Var Uses

type Var struct {
    Value interface{} // string | int64 | *big.Int | Ellipsis
    // contains filtered or unexported fields
}

Var is a node that represents '<var> = int|string|<expr>' definition.

This is a "terminal" definition, not a reference to something defined elsewhere. Usually a constant or some computation we replace with '...' in the docs.

func (*Var) Comments Uses

func (b *Var) Comments() string

func (*Var) Doc Uses

func (b *Var) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*Var) Name Uses

func (b *Var) Name() string

func (*Var) Span Uses

func (b *Var) Span() (syntax.Position, syntax.Position)

Package ast imports 2 packages (graph) and is imported by 4 packages. Updated 2019-10-17. Refresh now. Tools for package owners.