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

package docstring

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

Package docstring parses docstrings into more structured representation.

Understands doc strings of the following form.

"""Paragraph. Perhaps multiline.

Another paragraph. 

With indentation.

Args: 

arg1: desc,
  perhaps multiline, but must be intended.
arg2: ...

Returns: 

Intended free form text.

"""

Extracts all relevant parts of the docstring, deindending them as necessary.

Index

Package Files

docstring.go

type Field Uses

❖
type Field struct {
    Name string // name of the field
    Desc string // field's description, "\n" is replaced with " "
}

Field represents single "<name>: blah-blah-blah" definition.

type FieldsBlock Uses

❖
type FieldsBlock struct {
    Title  string  // how this block is titled, e.g. "Args" or "Fields"
    Fields []Field // each defined field
}

FieldsBlock is a section like "Args: ..." with a bunch of field definitions.

type Parsed Uses

❖
type Parsed struct {
    Description string        // deindented function description
    Fields      []FieldsBlock // all found fields blocks, e.g. "Args"
    Remarks     []RemarkBlock // all found remark blocks, e.g. "Returns"
}

Parsed is a parsed docstring.

It is a block of a text (presumably describing how to use a function), followed by a parsed arguments list (or equivalent, e.g. list of fields in a struct), followed by zero or more "remarks" blocks, which are named free-form text blocks. Most common remark block is "Returns", describing what the function returns.

func Parse Uses

❖
func Parse(doc string) *Parsed

Parse parses as much of the docstring as possible.

The expected grammar (loosely, since it is complicated by indentation handling): 

Docstring -> Block*
Block -> []string | (FieldsBlock | RemarkBlock)*
Fields -> ("Args:" | "Field:" | ...) Field+
Field -> "  <name>:" []string
RemarkBlock -> ("Returns:" | "Note:" | "...") []string

Never fails. May return incomplete or even empty object if the string format is unrecognized.

func (*Parsed) Args Uses

❖
func (p *Parsed) Args() []Field

Args is an alias for FieldsBlock("Args").Fields.

Returns arguments accepted by a function.

func (*Parsed) FieldsBlock Uses

❖
func (p *Parsed) FieldsBlock(title string) FieldsBlock

FieldsBlock returns a fields block with the given title or an empty block if not found.

func (*Parsed) RemarkBlock Uses

❖
func (p *Parsed) RemarkBlock(title string) RemarkBlock

RemarkBlock returns a remark block with the given title or an empty block if not found.

func (*Parsed) Returns Uses

❖
func (p *Parsed) Returns() string

Returns is an alias for RemarkBlock("Returns").Body.

Returns a description of a function's return value.

type RemarkBlock Uses

❖
type RemarkBlock struct {
    Title string // e.g. "Returns"
    Body  string // deindented  body
}

RemarkBlock represents things like "Returns:\n blah-blah".

We do not try to parse the body.

Package docstring imports 4 packages (graph) and is imported by 4 packages. Updated 2021-01-20. Refresh now. Tools for package owners.