docstring

Documentation

Overview

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

• type Field
• type FieldsBlock
• type Parsed
  • func Parse(doc string) *Parsed
  • func (p *Parsed) Args() []Field
  • func (p *Parsed) FieldsBlock(title string) FieldsBlock
  • func (p *Parsed) RemarkBlock(title string) RemarkBlock
  • func (p *Parsed) Returns() string
• type RemarkBlock

Types

type Field

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

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

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

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

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

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

Returns arguments accepted by a function.

func (*Parsed) FieldsBlock

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

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

func (p *Parsed) Returns() string

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

Returns a description of a function's return value.

type RemarkBlock

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.