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