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 (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.
Variables ¶
This section is empty.
Functions ¶
func ConfigPathParts ¶
ConfigPathParts splits configPath by its separator, the forward slash (/). It also trims leading and trailing slashes.
func SplitLastDot ¶
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 (*Driver) AddType ¶
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 ¶
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 ¶
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 ¶
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.
Source Files