moduledoc

README

ModuleDoc

This package implements the source analysis core of Caddy's module documentation system. It reads Go code to generate JSON docs -- kind of like godoc, but following JSON tags, and with special integration with Caddy's module architecture.

This package requires Go to be installed on the machine because it uses the packages package as well as running go commands directly. Inputs are fully-qualified package and type names, and outputs are JSON-structured type definitions and documentation. A backing data store is required for amortization.

A front-end can then be built to render the results, for example: both https://caddyserver.com/docs/json/ and https://caddyserver.com/docs/modules are powered by this package.

Author's disclaimer: This package comes with no guarantees of stability or correctness. The code is very hand-wavy, and I really had no idea what I was doing at the time, but at least it works! (Mostly.) Always refer to actual source code as authoritative documentation as the output of this package is not always perfect.

(c) 2019 Matthew Holt

Documentation

Index

• Constants
• func ConfigPathParts(configPath string) []string
• func SplitLastDot(input string) (before, after string)
• type CaddyModule
• type Driver
  • func New(database Storage) *Driver
  • func (d *Driver) AddType(packageName, typeName, version string) (*Value, error)
  • func (d *Driver) LoadModulesFromImportingPackage(packagePattern, version string) ([]CaddyModule, error)
  • func (d *Driver) LoadTypeByPath(configPath, version string) (exact, nearest *Value, err error)
  • func (d *Driver) LoadTypesByModuleID(moduleName string) ([]*Value, error)
  • func (d *Driver) TraverseType(path string, start *Value) (val, nearestType *Value, err error)
• type Storage
• type StructField
• type Type
• type Value

Constants

const CaddyCorePackage = "github.com/caddyserver/caddy/v2"

CaddyCorePackage is the import path of the Caddy core package.

Functions

func ConfigPathParts

func ConfigPathParts(configPath string) []string

ConfigPathParts splits configPath by its separator, the forward slash (/). It also trims leading and trailing slashes.

func SplitLastDot

func SplitLastDot(input string) (before, after string)

SplitLastDot splits input into two strings at the last dot. If there is no dot, then before will be empty string and after will be the input. Examples:

"github.com/caddyserver/caddy/v2.Config" => ("github.com/caddyserver/caddy/v2", "Config")
"http.handlers.file_server"              => ("http.handlers", "file_server")
"http"                                   => ("", "http")

Types

type CaddyModule

type CaddyModule struct {
	Name           string `json:"module_name,omitempty"`
	Representation *Value `json:"structure,omitempty"`
}

CaddyModule represents a Caddy module.

type Driver

type Driver struct {
	// contains filtered or unexported fields
}

Driver is an instance of the Caddy documentation system. It should be a long-lived value that is reused over the lifetime of a server.

An empty value is not valid; use New to obtain a valid value.

func New

func New(database Storage) *Driver

New constructs a new documentation system.

func (*Driver) AddType

func (d *Driver) AddType(packageName, typeName, version string) (*Value, error)

AddType loads, parses, inspects, and stores the type representation for the given type in the given package. This is generally used for bootstrapping the docs with the initial/base Config type, within which all modules are used.

func (*Driver) LoadModulesFromImportingPackage

func (d *Driver) LoadModulesFromImportingPackage(packagePattern, version string) ([]CaddyModule, error)

LoadModulesFromImportingPackage returns the Caddy modules (plugins) registered when package at its given version is imported.

func (*Driver) LoadTypeByPath

func (d *Driver) LoadTypeByPath(configPath, version string) (exact, nearest *Value, err error)

LoadTypeByPath loads the type representation at the given config path. It returns the exact value at that path and the nearest named type.

func (*Driver) LoadTypesByModuleID

func (d *Driver) LoadTypesByModuleID(moduleName string) ([]*Value, error)

LoadTypesByModuleID returns the type information for the Caddy module(s) with the given ID. It deeply dereferences the module(s) so that all type information and docs are included in the result.

func (*Driver) TraverseType

func (d *Driver) TraverseType(path string, start *Value) (val, nearestType *Value, err error)

TraverseType traverses the start value according to path until the end of path is reached or the value is no longer traverseable, in which case it returns an error. On success, it returns the value at the given path, along with its nearest (containing) defined type.

type Storage

type Storage interface {
	// GetTypeByName returns a type by its type name, comprising a
	// package path and the identifier/name within that package.
	GetTypeByName(packagePath, name, version string) (*Value, error)

	// GetTypesByCaddyModuleID returns matching types by the Caddy module ID.
	// (Caddy module IDs are not necessarily globally unique.)
	GetTypesByCaddyModuleID(caddyModuleID string) ([]*Value, error)

	// StoreType stores a type with the given package path and type name.
	StoreType(packagePath, typeName, version string, rep *Value) error

	// SetCaddyModuleName sets the module name for the type with the
	// given package and type name.
	SetCaddyModuleName(pkg *packages.Package, typeName, modName string) error
}

Storage describes the methods necessary for a documentation driver to be able to store and lookup type and value information.

type StructField

type StructField struct {
	Key   string `json:"key"`
	Value *Value `json:"value"`
	Doc   string `json:"doc,omitempty"`
}

StructField contains information about a struct field.

type Type

type Type string

Type represents a funamdental type. Recognized values are defined as constants in this package. Most of the types are Go primitives, but a few are more complex types that we want/need to handle properly for documentation purposes. For example, it's obvious that we need a string type, but we also need a struct type so that we can render a struct's fields. Ultimately, all named types are expected to boil down to the types we recognize so we can express them properly in the generated documentation.

const (
	// Go primitives
	Bool    Type = "bool"
	Int     Type = "int"
	Uint    Type = "uint"
	Float   Type = "float"
	Complex Type = "complex"
	String  Type = "string"

	// Complex or structural types
	Struct Type = "struct"
	Array  Type = "array"
	Map    Type = "map"

	// Caddy-specific types
	Module    Type = "module"
	ModuleMap Type = "module_map"
)

Possible types that are recognized by the documentation system.

type Value

type Value struct {
	// Indicates the fundamental type of the value.
	Type Type `json:"type,omitempty"`

	// The local name of the type from the source code.
	TypeName string `json:"type_name,omitempty"`

	// For struct types, these are the struct fields.
	StructFields []*StructField `json:"struct_fields,omitempty"`

	// For map types, this describes the map keys.
	MapKeys *Value `json:"map_keys,omitempty"`

	// For map types, this describes the map values.
	// For array types, this describes the array elements.
	Elems *Value `json:"elems,omitempty"`

	// The documentation as found from the source code's godoc.
	Doc string `json:"doc,omitempty"`

	// If this value's type is the reuse of an existing
	// named type for which we already have the structure
	// documented, SameAs contains the fully-qualified
	// type name and possibly version (fqtn@version).
	SameAs string `json:"same_as,omitempty"`

	// If this value is fulfilled by a Caddy module,
	// this should be the module's namespace.
	ModuleNamespace *string `json:"module_namespace,omitempty"`

	// If this value is fulfilled by a Caddy module and
	// is configured by declaring the module's name inline
	// with its struct, this is the name of the key with
	// which the module name is specified.
	ModuleInlineKey *string `json:"module_inline_key,omitempty"`
}

Value describes a config value. *Technically* it actually describes a type, but since our purpose is documentation, all uses of the type end up becoming values, so from the user's perspective, they are values, even though though they are only plausible/template values derived from types in source code.