sherpadoc

README

sherpadoc - documentation for sherpa API's

Go package containing type defintions for sherpa documentation for encoding to and decoding from json.
Also contains the sherpadoc command reads Go code and writes sherpadoc JSON.

Use together with the sherpa library, github.com/mjl-/sherpa.
Read more about sherpa at https://www.ueber.net/who/mjl/sherpa/

# About

Written by Mechiel Lukkien, mechiel@ueber.net.
Bug fixes, patches, comments are welcome.
MIT-licensed, see LICENSE.

# todo

- major cleanup required. too much parsing is done that can probably be handled by the go/* packages.
- check that all cases of embedding work
- check that all cross-package referencing (ast.SelectorExpr) works
- better cli syntax for replacements, and always replace based on fully qualified names. currently you need to specify both the fully qualified and unqualified type paths.
- see if order of items in output depends on a map somewhere, i've seen diffs for generated jsons where a type was only moved, not modified.
- better error messages and error handling, stricter parsing
- support type aliases
- support plain iota enums? currently only simple literals are supported for enums.
- support complete expressions for enum consts?
- find out which go constructs people want to use that aren't yet implemented by sherpadoc
- error or warn when omitempty is set for non-pointer?
- write tests

Documentation

Overview

Package sherpadoc contains types for reading and writing documentation for sherpa API's.

Index

• Constants
• func Check(doc *Section) (retErr error)
• type Arg
• type Field
• type Function
• type Ints
• type Section
• type Strings
• type Struct

Constants

const (
	// SherpadocVersion is the sherpadoc version generated by this command.
	SherpadocVersion = 1
)

Functions

func Check

func Check(doc *Section) (retErr error)

Check walks the sherpa section and checks it for correctness. It checks for:

- Duplicate type names. - Duplicate parameter or return names. - References to types that are not defined. - Validity of typewords.

Types

type Arg

type Arg struct {
	Name      string   // Name of the argument.
	Typewords []string // Typewords is an array of tokens describing the type.
}

Arg is the name and type of a function parameter or return value.

Production rules:

basictype := "bool" | "int8", "uint8" | "int16" | "uint16" | "int32" | "uint32" | "int64" | "uint64" | "int64s" | "uint64s" | "float32" | "float64" | "string" | "timestamp"
array := "[]"
map := "{}"
identifier := [a-zA-Z][a-zA-Z0-9]*
type := "nullable"? ("any" | basictype | identifier | array type | map type)

It is not possible to have inline structs in an Arg. Those must be encoded as a named type.

type Field

type Field struct {
	Name      string
	Docs      string
	Typewords []string
}

Field is a single field of a struct type. The type can reference another named type.

type Function

type Function struct {
	Name    string // Name of the function.
	Docs    string // Text or markdown, describing the function, its parameters, return types and possible errors.
	Params  []Arg
	Returns []Arg
}

Function contains the documentation for a single function.

type Ints

type Ints struct {
	Name   string
	Docs   string
	Values []struct {
		Name  string
		Value int
		Docs  string
	}
}

Ints is a type representing an enum with integers as types.

type Section

type Section struct {
	Name      string      // Name of an API section.
	Docs      string      // Explanation of the API in text or markdown.
	Functions []*Function // Functions in this section.
	Sections  []*Section  // Subsections, each with their own documentation.
	Structs   []Struct    // Structs as named types.
	Ints      []Ints      // Int enums as named types.
	Strings   []Strings   // String enums used as named types.

	Version          string `json:",omitempty"` // Version if this API, only relevant for the top-level section of an API. Typically filled in by server at startup.
	SherpaVersion    int    // Version of sherpa this API implements. Currently at 0. Typically filled in by server at startup.
	SherpadocVersion int    `json:",omitempty"` // Version of the sherpadoc format. Currently at 1, the first defined version. Only relevant for the top-level section of an API.
}

Section represents documentation about a Sherpa API section, as returned by the "_docs" function.

type Strings

type Strings struct {
	Name   string
	Docs   string
	Values []struct {
		Name  string
		Value string
		Docs  string
	}
}

Strings is a type representing an enum with strings as values.

type Struct

type Struct struct {
	Name   string
	Docs   string
	Fields []Field
}

Struct is a named compound type.