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.
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 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 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.
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.
Args is an alias for FieldsBlock("Args").Fields.
Returns arguments accepted by a function.
func (p *Parsed) FieldsBlock(title string) FieldsBlock
FieldsBlock returns a fields block with the given title or an empty block if not found.
func (p *Parsed) RemarkBlock(title string) RemarkBlock
RemarkBlock returns a remark block with the given title or an empty block if not found.
Returns is an alias for RemarkBlock("Returns").Body.
Returns a description of a function's return value.
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.