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 // 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

func (b *ExternalReference) Comments() string

func (*ExternalReference) Doc

func (b *ExternalReference) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*ExternalReference) Name

func (b *ExternalReference) Name() string

func (*ExternalReference) Span

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

type Function

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

Function is a node that represents a function definition.

func (*Function) Comments

func (b *Function) Comments() string

func (*Function) Doc

func (n *Function) Doc() string

Doc extracts the documentation from the docstring.

func (*Function) Name

func (b *Function) Name() string

func (*Function) Span

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

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

func (b *Invocation) Comments() string

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.

func (*Invocation) Name

func (b *Invocation) Name() string

func (*Invocation) Span

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

type Module

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

Module is a parsed Starlark file.

func ParseModule

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

ParseModule parses a single Starlark module.

Filename is only used when recording position information.

func (*Module) Comments

func (b *Module) Comments() string

func (*Module) Doc

func (n *Module) Doc() string

Doc extracts the documentation from the docstring.

func (*Module) Name

func (b *Module) Name() string

func (*Module) Span

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

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

func (b *Namespace) Comments() string

func (*Namespace) Doc

func (b *Namespace) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*Namespace) EnumNodes

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

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

func (*Namespace) Name

func (b *Namespace) Name() string

func (*Namespace) Span

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

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

func (*Reference) Comments

func (b *Reference) Comments() string

func (*Reference) Doc

func (b *Reference) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*Reference) Name

func (b *Reference) Name() string

func (*Reference) Span

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

type Var

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

func (b *Var) Comments() string

func (*Var) Doc

func (b *Var) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*Var) Name

func (b *Var) Name() string

func (*Var) Span

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

Source Files