sherpadoc

package module
v0.0.18 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 19, 2024 License: MIT Imports: 1 Imported by: 16

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

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.

func IsBasicType added in v0.0.16 

func IsBasicType(name string) bool

IsBasicType returns whether name is a basic type, like int32, string, any, timestamp, etc.

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 IntValue added in v0.0.18 

type IntValue struct {
	Name  string
	Value int64
	Docs  string
}

type Ints 

type Ints struct {
	Name   string
	Docs   string
	Values []IntValue
}

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 StringValue added in v0.0.18 

type StringValue struct {
	Name  string
	Value string
	Docs  string
}

type Strings 

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

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
sherpadoc command
Sherpadoc parses Go code and outputs sherpa documentation in JSON.
 Sherpadoc parses Go code and outputs sherpa documentation in JSON.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.