godoc

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Jul 1, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Overview

Package godoc parses, resolves, and formats Go documentation.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrPackageNotFound identifies a resolved package miss after every source fetcher declines the lookup.
	ErrPackageNotFound = errors.New("package not found")
	// ErrLookupNotFound identifies a symbol, method, or field miss after package candidates were exhausted.
	ErrLookupNotFound = errors.New("lookup not found")
)
View Source 
var (
	ErrSourceNotApplicable = errors.New("source fetcher not applicable")
	ErrNoGoFiles           = errors.New("no Go source files")
	ErrOutsideModule       = errors.New("local package path is outside module")
)
View Source 
var ErrNoParseableFiles = errors.New("no parseable Go files")
View Source 
var ErrPackageRequired = errors.New("package is required")

Functions

func FormatLookup 

func FormatLookup(parsed *ParsedPackage, lookup Lookup, opts Options) (string, error)

FormatLookup renders package documentation for a resolved lookup.

func FormatPackage 

func FormatPackage(pkg *doc.Package, fset *token.FileSet, aliases ImportAliases, opts Options) (string, error)

FormatPackage renders package documentation as terminal text.

func LookupExists 

func LookupExists(parsed *ParsedPackage, lookup Lookup, opts Options) bool

LookupExists reports whether parsed contains the requested lookup.

func WriteCache 

func WriteCache(fs afero.Fs, cacheDir string, resolved ResolvedModule, files []SourceFile) error

WriteCache writes package source files into a Go module cache layout.

Types

type Client 

type Client struct {
	Resolver     Resolver
	PackageIndex PackageIndex
	Current      CurrentPackage
}

Client orchestrates source resolution, parsing, and formatting.

func NewDefaultClient 

func NewDefaultClient(fs afero.Fs) (*Client, error)

NewDefaultClient assembles production source fetchers.

func (Client) Doc 

func (c Client) Doc(ctx context.Context, opts Options) (string, error)

type CurrentPackage 

type CurrentPackage struct {
	WorkDir    string
	ModuleDir  string
	ModulePath string
}

CurrentPackage describes the working package for no-argument and local symbol lookups.

type EnvGitAuthProvider 

type EnvGitAuthProvider struct {
	Lookup func(string) (string, bool)
}

EnvGitAuthProvider reads Git HTTPS tokens from the environment.

func (EnvGitAuthProvider) Auth 

func (p EnvGitAuthProvider) Auth() transport.AuthMethod

type GitAuthProvider 

type GitAuthProvider interface {
	Auth() transport.AuthMethod
}

type GitCloneRequest 

type GitCloneRequest struct {
	RepoURL       string
	Auth          transport.AuthMethod
	ReferenceName plumbing.ReferenceName
}

GitCloneRequest describes one in-memory Git clone.

type GitCloner 

type GitCloner interface {
	Clone(context.Context, GitCloneRequest) (afero.Fs, error)
}

GitCloner clones a repository and returns an afero filesystem rooted at it.

type GitFetcher 

type GitFetcher struct {
	GOPRIVATE    string
	HTTPClient   *http.Client
	DiscoveryURL discoveryFunc
	AuthProvider GitAuthProvider
	Cloner       GitCloner
	CacheFS      afero.Fs
	CacheDir     string
}

GitFetcher loads private package source from Git repositories.

func (GitFetcher) Fetch 

func (f GitFetcher) Fetch(ctx context.Context, pkg string, opts Options) (PackageSource, error)

type GoGitCloner 

type GoGitCloner struct{}

GoGitCloner clones with go-git into memory and exposes the worktree as afero.

func (GoGitCloner) Clone 

func (GoGitCloner) Clone(ctx context.Context, req GitCloneRequest) (afero.Fs, error)

type ImportAliases 

type ImportAliases map[string]string

ImportAliases maps local import aliases to import paths.

type IndexedPackage 

type IndexedPackage struct {
	ImportPath string
	Dir        string
}

IndexedPackage is one locally known package match.

type LocalPackageIndex 

type LocalPackageIndex struct {
	FS         afero.Fs
	ModuleDir  string
	ModulePath string
	GOROOT     string
	ModCache   string
}

LocalPackageIndex indexes packages that are already known on local disk.

func (LocalPackageIndex) MatchSuffix 

func (i LocalPackageIndex) MatchSuffix(suffix string) ([]IndexedPackage, error)

type LocalSourceFetcher 

type LocalSourceFetcher struct {
	FS         afero.Fs
	ModuleDir  string
	ModulePath string
}

LocalSourceFetcher loads packages addressed by ./ or ../ paths.

func (LocalSourceFetcher) Fetch 

func (f LocalSourceFetcher) Fetch(_ context.Context, pkg string, _ Options) (PackageSource, error)

type Lookup 

type Lookup struct {
	Package  string
	UserPath string
	Symbol   *SymbolLookup
}

Lookup is the normalized documentation target.

type LookupCandidate 

type LookupCandidate struct {
	Package              string
	UserPath             string
	Symbol               *SymbolLookup
	Kind                 LookupCandidateKind
	ContinueOnSymbolMiss bool
}

LookupCandidate is one package/symbol interpretation of raw doc arguments.

type LookupCandidateKind 

type LookupCandidateKind int

LookupCandidateKind explains why a candidate was generated. 

const (
	LookupCurrentPackage LookupCandidateKind = iota
	LookupFullPackage
	LookupSuffix
	LookupLocalPath
)

type LookupNotFoundError 

type LookupNotFoundError struct {
	Symbol   *SymbolLookup
	Query    string
	Attempts []string
}

LookupNotFoundError describes a failed lookup after one or more package candidates were checked.

func (LookupNotFoundError) Error 

func (e LookupNotFoundError) Error() string

func (LookupNotFoundError) Unwrap 

func (e LookupNotFoundError) Unwrap() error

type LookupResolver 

type LookupResolver struct {
	Resolver     Resolver
	PackageIndex PackageIndex
	Current      CurrentPackage
}

LookupResolver resolves official go doc argument forms to package source.

func (LookupResolver) Resolve 

func (r LookupResolver) Resolve(ctx context.Context, opts Options) (ResolvedLookup, error)

type ModCacheFetcher 

type ModCacheFetcher struct {
	FS       afero.Fs
	CacheDir string
	Deps     map[string]module.Version
}

ModCacheFetcher reads package source from an existing module cache.

func (ModCacheFetcher) Fetch 

func (f ModCacheFetcher) Fetch(_ context.Context, pkg string, opts Options) (PackageSource, error)

type Options 

type Options struct {
	Args          []string
	Package       string
	Symbol        string
	Version       string
	All           bool
	Short         bool
	Src           bool
	Unexported    bool
	CaseSensitive bool
	Cmd           bool
}

Options describes a documentation lookup request.

type PackageIndex 

type PackageIndex interface {
	MatchSuffix(string) ([]IndexedPackage, error)
}

PackageIndex finds locally known packages by import path suffix.

type PackageNotFoundError 

type PackageNotFoundError struct {
	Package string
}

PackageNotFoundError names the package that no source fetcher could load.

func (PackageNotFoundError) Error 

func (e PackageNotFoundError) Error() string

func (PackageNotFoundError) Unwrap 

func (e PackageNotFoundError) Unwrap() error

type PackageSource 

type PackageSource struct {
	ImportPath string
	Dir        string
	Files      []SourceFile
	Module     module.Version
	Version    string
}

PackageSource is the source material for one package.

type ParsedPackage 

type ParsedPackage struct {
	Package *doc.Package
	Fset    *token.FileSet
	Files   []*ast.File
	Aliases ImportAliases
}

ParsedPackage is the documentation model plus metadata needed for formatting.

func ParsePackage 

func ParsePackage(importPath string, files []SourceFile, mode doc.Mode) (*ParsedPackage, error)

ParsePackage parses source files into Go documentation.

type ProxyFetcher 

type ProxyFetcher struct {
	Client       *http.Client
	ProxyURL     string
	DiscoveryURL discoveryFunc
	CacheFS      afero.Fs
	CacheDir     string
}

ProxyFetcher loads public module source from a single Go module proxy.

func (ProxyFetcher) Fetch 

func (f ProxyFetcher) Fetch(ctx context.Context, pkg string, opts Options) (PackageSource, error)

type ReplaceSourceFetcher 

type ReplaceSourceFetcher struct {
	FS           afero.Fs
	Replacements map[string]string
}

ReplaceSourceFetcher loads packages from local go.mod replace directives.

func (ReplaceSourceFetcher) Fetch 

func (f ReplaceSourceFetcher) Fetch(_ context.Context, pkg string, _ Options) (PackageSource, error)

type ResolvedLookup 

type ResolvedLookup struct {
	Source   PackageSource
	Lookup   Lookup
	Attempts []string
}

ResolvedLookup is a lookup bound to fetched source.

type ResolvedModule 

type ResolvedModule struct {
	Path        string
	Version     string
	PackagePath string
}

ResolvedModule identifies a concrete module version and package within it.

type Resolver 

type Resolver struct {
	Fetchers []SourceFetcher
}

Resolver tries source fetchers in configured priority order.

func (Resolver) Fetch 

func (r Resolver) Fetch(ctx context.Context, pkg string, opts Options) (PackageSource, error)

type SourceFetcher 

type SourceFetcher interface {
	Fetch(context.Context, string, Options) (PackageSource, error)
}

SourceFetcher loads package source for one route.

type SourceFile 

type SourceFile struct {
	Name string
	Data []byte
}

SourceFile is a Go source file loaded from any supported source.

type StdlibSourceFetcher 

type StdlibSourceFetcher struct {
	FS     afero.Fs
	GOROOT string
}

StdlibSourceFetcher loads packages from GOROOT/src.

func (StdlibSourceFetcher) Fetch 

func (f StdlibSourceFetcher) Fetch(_ context.Context, pkg string, _ Options) (PackageSource, error)

type SymbolLookup 

type SymbolLookup struct {
	Name   string
	Member *string
}

SymbolLookup identifies a top-level symbol and optional method or field.

Source Files

View all Source files

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.