comments

Documentation

Overview

Package comments provides utilities for extracting comments from Go source code.

This package handles the bridge between go/types (semantic view) and go/ast (syntactic view) using position-based lookup. It extracts:

• Package-level comments and copyright headers
• Doc comments for functions, types, constants, and variables
• Body comments from within functions and type declarations
• Domain descriptions from package comments

The Extractor type maintains the context needed for position-based lookup, including the file set, files map, and declaration cache.

Index

• func BuildFilesMap(pkg *packages.Package) map[*token.File]*ast.File
• type Extractor
  • func New(syntaxPackage []*ast.File, fileSet *token.FileSet, ...) *Extractor
  • func (e *Extractor) ExtractComments(object types.Object) *ast.CommentGroup
  • func (e *Extractor) ExtractCopyright() *ast.CommentGroup
  • func (e *Extractor) ExtractDomainDescriptions() []model.ExtraComment
  • func (e *Extractor) ExtractExtraComments(object types.Object) []model.ExtraComment
  • func (e *Extractor) ExtractPackageComments() *ast.CommentGroup

Functions

func BuildFilesMap

func BuildFilesMap(pkg *packages.Package) map[*token.File]*ast.File

BuildFilesMap constructs a lookup index to help bridge token position vs ast.File.

This creates a map from token.File (file metadata) to ast.File (syntax tree), enabling O(1) lookup after O(n) construction.

Types

type Extractor

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

Extractor extracts comments from Go source code using position-based AST/types bridging.

func New

func New(syntaxPackage []*ast.File, fileSet *token.FileSet, filesMap map[*token.File]*ast.File) *Extractor

New creates a comment extractor.

The syntaxPackage provides access to all AST files in the package. The fileSet and filesMap enable position-based lookup to bridge types.Object to ast.Decl.

func (*Extractor) ExtractComments

func (e *Extractor) ExtractComments(object types.Object) *ast.CommentGroup

ExtractComments retrieves the docstring for an object.

Never returns nil: if no comment is present an empty but valid ast.CommentGroup is returned.

NOTE: comment prioritization rule is:

1. GenDecl.Doc = leading comment for the entire declaration block
2. Spec.Doc = individual doc for that specific spec

func (*Extractor) ExtractCopyright

func (e *Extractor) ExtractCopyright() *ast.CommentGroup

ExtractCopyright scans source files and expects that at least one contains a leading comment line with the string "copyright".

Never returns nil.

func (*Extractor) ExtractDomainDescriptions

func (e *Extractor) ExtractDomainDescriptions() []model.ExtraComment

ExtractDomainDescriptions extracts domain descriptions from package-level comments.

Returns nil if no domain descriptions are found.

func (*Extractor) ExtractExtraComments

func (e *Extractor) ExtractExtraComments(object types.Object) []model.ExtraComment

ExtractExtraComments retrieves body comments (inside functions or type declarations).

Returns nil if no extra comments are found.

func (*Extractor) ExtractPackageComments

func (e *Extractor) ExtractPackageComments() *ast.CommentGroup

ExtractPackageComments finds the package-level comment that describes the source package.

This is a single comment group from the first file that has package documentation. Never returns nil.