Skip to content
internal/extractors/golang
Updated
On this page

Resolving selfdoc's directives against Go source: package documentation, exported declarations, struct fields and test bodies, read one package at a time.

#internal/extractors/golang

#internal/extractors/golang

Package golang resolves selfdoc's directives against Go source.

It is a line scanner built on regular expressions, not a parse of the language: no Go toolchain is required, and a package that does not compile still documents. That is a deliberate trade, and it has consequences a reader of the generated pages can see -- a capitalized field key inside a composite literal in a var block is counted as an exported symbol, for instance. Those behaviors are reproduced here rather than fixed, because the pages, the coverage numbers and the stored description hashes of every Go project selfdoc documents were all produced by this scanner. Replacing it with a go/ast walk is its own change, with its own diff to review.

#Extractor

Go go
type Extractor struct

Extractor reads Go source by scanning its lines.

#New

Go go
func New() extractors.Extractor

New builds the Go extractor. Every answer comes from reading files, which is not an effect.

#Extractor.Detect

Go go
func (e *Extractor) Detect(dir string) bool

Detect reports whether dir carries a Go module's marker file.

#Extractor.FileExtensions

Go go
func (e *Extractor) FileExtensions() []string { return []string{".go"} }

FileExtensions is the single extension Go owns.

#Extractor.ResolvePath

Go go
func (e *Extractor) ResolvePath(pathArg string, sourcePaths []string, baseDir string) string

ResolvePath resolves a package path to its directory. Go's unit of documentation is the package, so this returns a directory where the other extractors return a file.

#Extractor.PublicSymbols

Go go
func (e *Extractor) PublicSymbols(file string) ([]string, error)

PublicSymbols lists the exported symbols a Go file declares.

A method is named by its receiver type (Server.Handle) so two types' methods of the same name do not collide. Lines inside line and block comments are skipped, and const and var blocks are scanned for their members.

#Extractor.ModuleDocstring

Go go
func (e *Extractor) ModuleDocstring(path string) (string, error)

ModuleDocstring is a Go package's doc comment, with soft-wrapped prose joined.

path may be a directory -- what ResolvePath returns -- or a single .go file, whose directory is read instead. Test files are skipped.

#Extractor.SymbolDetails

Go go
func (e *Extractor) SymbolDetails(file, symbol string) (*extractors.SymbolDetails, error)

SymbolDetails reports a Go function's or method's parameters and return type, and whether its doc comment covers them.

file may be a directory -- what ResolvePath returns -- in which case every non-test .go file in it is scanned in name order. A dotted name (Server.Handle) requires the receiver type to match; a plain name matches any function or method so spelled.

Search