mod

Documentation

Overview

Package mod processes a directory with a go.mod file and extracts the documentation.

This process complements the go/doc package in that it

• Specifically is designed to output HTML, and
• It creates a structure that is easily consumed by Go templates.

Index

• Constants
• type Constant
• type Function
• type HTMLer
• type Method
• type Module
  • func NewModule(modPath string) *Module
• type Package
  • func NewPackage(p *doc.Package, fset *token.FileSet, dirPath string, module *Module) *Package
  • func (p *Package) HTML(t any) string
• type PathPart
• type Type
• type Variable

Constants

const ExternalPackageDoc = `https://pkg.go.dev/`

ExternalPackageDoc is the URL for documentation of packages outside the module.

Types

type Constant

type Constant struct {
	Code        string
	Names       []string
	CommentHtml string
	Flags       map[string]string
}

Constant represents a single line constant or a constant group declaration

type Function

type Function struct {
	Code        string
	Name        string
	CommentHtml string
	Flags       map[string]string
}

Function represents a simple top-level function that is not associated with a type.

type HTMLer

type HTMLer interface {
	// contains filtered or unexported methods
}

type Method

type Method struct {
	Code        string
	Name        string
	CommentHtml string

	// The type of the receiver
	Receiver string
	// EmbeddedType is the name of the type this method is associated with if its embedded in the main type.
	EmbeddedType string
	Level        int
	Flags        map[string]string
}

Method represents a method associated with a type.

type Module

type Module struct {
	// Name is the module name extracted from the go.mod file.
	Name string
	// DirName is the name of the directory holding the module. This is not always the same, but often is.
	DirName string
	// Packages is the documentation for all the packages in the module.
	// The first package in the list represents the package in the same
	// directory as the go.mod file, if there is a package there.
	Packages map[string]*Package
}

Module represents the documentation for an entire module.

Module is structured to be easily consumed by Go templates.

func NewModule

func NewModule(modPath string) *Module

NewModule walks a module directory, returning a Module structure.

The directory dirPath should contain a go.mod file.

type Package

type Package struct {
	// DocPkg is the package structure as extracted from Go doc.
	DocPkg *doc.Package
	// Fset is the fileset of the files in package.
	Fset *token.FileSet

	// Module is the parent module structure, put here for convenience
	Module *Module

	// Path is the relative path from the home directory to the package. It will always be separate by "/", even on windows.
	Path string

	// PathParts are the names of the directories leading from the home directory to the package.
	// The first directory is the name of the directory holding the module.
	PathParts   []PathPart
	Name        string
	ImportPath  string
	Synopsis    string
	CommentHtml string

	// FileName is the name of the documentation file corresponding to this package.
	FileName  string
	Constants []Constant
	Variables []Variable
	Functions []Function
	Types     []*Type
	// contains filtered or unexported fields
}

Package is a deconstruction of a package into its documentation parts for relatively easy consumption by a template.

This is the .Package that is sent to the package.tmpl templat.

All strings listed are not escaped. Call [HTML] on an item to convert it to html.

func NewPackage

func NewPackage(p *doc.Package, fset *token.FileSet, dirPath string, module *Module) *Package

func (*Package) HTML

func (p *Package) HTML(t any) string

HTML should be called from within a template to convert the passed item to html.

type PathPart

type PathPart struct {
	// DirName is the name of the directory
	DirName string
	// DocFile is the name of the documentation file associated with the package there, or the empty
	// string if there is no documentation for this part of the path.
	DocFile string
}

PathPart is a directory in a directory list that refers to a package.

type Type

type Type struct {
	Code        string
	Name        string
	CommentHtml string
	Flags       map[string]string
	Type        string // If we know its one of the types we can determine, we will name it
	Constants   []Constant
	Variables   []Variable
	Functions   []Function
	Methods     []Method
}

Type represents a type definition. This could by a simple type, an interface, or a structure

type Variable

type Variable struct {
	Code        string
	Names       []string
	CommentHtml string
	Flags       map[string]string
}

Variable represents a variable declaration, or a group of variables declared together with the same type.