gosrc

Package gosrc is the part of the pipeline of doc2go responsible for finding Go packages and loading information about them.

package gosrc

import "go.abhg.dev/doc2go/internal/gosrc"

Package gosrc is the part of the pipeline of doc2go responsible for finding Go packages and loading information about them.

It provides a Finder to search for packages. These produce [PackageRef]s, which are references to packages. PackageRefs are lightweight and do not contain significant package data, so many of them can be in memory at once. Parser is used to load the actual package data from PackageRefs.

Index

Constants

const Builtin = "builtin"

Builtin is the value for [EntityRefLabel.ImportPath] if the entity referenced is a Go built-in.

Functions

func FormatExample

func FormatExample(bs []byte) []byte

FormatExample prepares an example's source code for presentation in documentation. To do this, it performs a couple transformations.

If the example is not a full-file example, it's likely wrapped in a BlockStmt -- with a '{' and '}'. This function removes those braces and unindent the code inside.

Secondly, if the expected output is included in a comment at the end of the example, this function removes that comment and any blank lines before it. This is done because the output is already included separately in the rendered documentation.

Types

type DeclFormatter

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

DeclFormatter formats declarations from a single Go package.

This may be re-used between declarations, but not across packages.

func NewDeclFormatter

func NewDeclFormatter(fset *token.FileSet, topLevelDecls []string) *DeclFormatter

NewDeclFormatter builds a new DeclFormatter for the given package.

func (*DeclFormatter) Debug

func (f *DeclFormatter) Debug(debug bool)

Debug sets whether the formatter is in debug mode. In debug mode, the formatter may panic.

func (*DeclFormatter) FormatDecl

func (f *DeclFormatter) FormatDecl(decl ast.Decl) (src []byte, regions []Region, err error)

FormatDecl formats a declaration back into source code, and reports regions inside it where anything of note happens.

type DeclLabel

type DeclLabel struct {
	// Name of the parent inside which the child is declared.
	// Empty for vars and consts.
	Parent string

	// Name of the declared entity.
	Name string
}

DeclLabel marks declaration sites for struct fields, interface methods, and vars and consts.

type EntityRefLabel

type EntityRefLabel struct {
	// Import path of the package defining the referenced entity.
	//
	// This is empty for local references, and "builtin" for
	// built-ins.
	ImportPath string

	// Name of the entity referenced.
	Name string
}

EntityRefLabel marks a region that references another entity.

type Finder

type Finder struct {
	PackagesConfig *packages.Config

	// Build tags to enable when searching for packages.
	Tags []string

	// Logger to write regular log messages to.
	Log *log.Logger

	// Logger to write debug messages to.
	//
	// Use nil to disable debug logging.
	DebugLog *log.Logger
}

Finder searches for and returns Go package references using the go/packages library.

The zero value of this is ready to use.

func (*Finder) FindPackages

func (f *Finder) FindPackages(patterns ...string) ([]*PackageRef, error)

FindPackages searches for packages matching the given import path patterns, and returns references to them.

type ImportedPackage

type ImportedPackage struct {
	Name       string
	ImportPath string
}

ImportedPackage is a package imported by another package.

type Label

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

Label holds structured information about a Region.

type Package

type Package struct {
	// Name of the package.
	Name string

	// Import path of the package.
	ImportPath string

	// Parsed ASTs of all source files in the package.
	Syntax []*ast.File

	// Parsed ASTs of all test files in the package.
	TestSyntax []*ast.File

	// FileSet used to parse these files.
	Fset *token.FileSet

	// Names of top-level declarations defined in this package.
	TopLevelDecls []string
}

Package is a package that has been loaded from disk.

type PackageRef

type PackageRef struct {
	// Name of the package.
	Name string

	// Import path of the package.
	ImportPath string

	// List of .go files in the package.
	Files []string

	// List of _test.go files in the package.
	TestFiles []string

	// Packages imported by this package.
	Imports []ImportedPackage
}

PackageRef is a reference to a package.

It holds information necessary to load a package, but doesn't yet load it.

type PackageRefLabel

type PackageRefLabel struct {
	// Import path of the package.
	ImportPath string
}

PackageRefLabel marks a region that references another Go package.

type Parser

type Parser struct{}

Parser loads the contents of a package by parsing it from source.

func (*Parser) ParsePackage

func (*Parser) ParsePackage(ref *PackageRef) (*Package, error)

ParsePackage parses all files in the package at the given path and fills a Package object with the result.

type Region

type Region struct {
	// Label signifying what's special about this region.
	Label Label

	// Byte offset inside the formatted source code
	// where this region begins.
	Offset int

	// Length of this region.
	Length int
}

Region is a region of a declaration's source code that represents something special.

Inside formatted source code src, a region r's label applies to:

src[r.Offset:r.Offset+r.Length]