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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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.

Source Files