Documentation
¶
Overview ¶
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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Ellipsis ¶
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 ¶
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 ¶
type ExternalReference struct {
ExternalName string // name of the symbol in the loaded module
Module string // normalized 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".
type Function ¶
type Function struct {
// contains filtered or unexported fields
}
Function is a node that represents a function definition.
type Invocation ¶
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) Doc ¶
func (b *Invocation) Doc() string
Doc extracts the documentation for the symbol from its comments.
func (*Invocation) EnumNodes ¶
func (inv *Invocation) EnumNodes() []Node
EnumNodes returns list of nodes that represent arguments.
type Module ¶
type Module struct {
Namespace // all top-level symbols
// contains filtered or unexported fields
}
Module is a parsed Starlark file.
func ParseModule ¶
ParseModule parses a single Starlark module.
Filename is only used when recording position information.
type Namespace ¶
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) Doc ¶
func (b *Namespace) Doc() string
Doc extracts the documentation for the symbol from its comments.
type Node ¶
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 ¶
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(...)).
type Var ¶
type Var struct {
Value any // 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.
Source Files