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 (seems like we will include duplicates: when a struct has fields that override an embedded struct, we generate duplicate fields). - check that all cross-package referencing (ast.SelectorExpr) works - better cli syntax for replacements and renames, 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. perhaps the type was discovered earlier/later because of other type changes. we may want to sort sections,methods,types in the output. - 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 - when to make a field nullable. when omitempty is set? (currently yes), when field is a pointer type (currently yes). should we have a way to prevent nullable without omitempty set, or make field a pointer without it being nullable? - write tests
Documentation ¶
Overview ¶
Package sherpadoc contains types for reading and writing documentation for sherpa API's.
Index ¶
Constants ¶
View Source
const (
// SherpadocVersion is the sherpadoc version generated by this command.
SherpadocVersion = 1
)
Variables ¶
This section is empty.
Functions ¶
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 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 int64 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.
Click to show internal directories.
Click to hide internal directories.