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