#internal/excludes

#internal/excludes

Package excludes is the single authority for which source paths a project's docs cover.

Every source walk in selfdoc -- page generation, coverage counting, and the list-modules directive -- decides the same way which files and directories are part of the documented project. Keeping the patterns and the matcher here means a path excluded from the generated pages cannot be advertised by a listing directive, and vice versa.

The inputs are two: [DefaultExcludes], applied everywhere, and the gen.exclude list from selfdoc.json, which a project adds to it. [SkipDirs] is separate and unconditional: environment and build directories that are never source, pruned from a walk before any pattern is tested.

#DefaultExcludes

var DefaultExcludes = []string{

DefaultExcludes are the exclusion patterns always applied in addition to the project-configured ones. They are matched against both the full relative path and the basename, so "test_*" matches test_core.py at any depth.

#SkipDirs

var SkipDirs = map[string]bool{

SkipDirs are the directory names always pruned during a source walk. A walker drops them before descending, so nothing inside them is ever read.

#ShouldSkipDir

func ShouldSkipDir(dirname string) bool

ShouldSkipDir reports whether a directory name should be pruned during a source walk.

#GoToolchainIgnoresDir

func GoToolchainIgnoresDir(name string) bool

GoToolchainIgnoresDir reports whether the Go toolchain ignores a directory of this name, so nothing under it is part of any Go package.

cmd/go never builds a directory named "testdata" or "vendor", nor one whose name begins with "." or "_". Documenting such a directory as a package advertises code that "go build ./..." does not compile.

#GoToolchainIgnoresPath

func GoToolchainIgnoresPath(relDir string) bool

GoToolchainIgnoresPath reports whether any component of a slash-separated relative directory path is ignored by the Go toolchain.

A path of "." names the walk's own root, which no component test applies to.

#IsExcluded

func IsExcluded(relPath string, excludePatterns []string) bool

IsExcluded reports whether a relative path matches any exclusion glob.

A "**/" prefix means "match at any depth": the prefix is stripped and the rest is tested against the whole path, the basename, and every directory component. A plain pattern is tested the same three ways, and then -- when stripping changed it -- once more in its original spelling against the whole path.

#PatternsFor

func PatternsFor(config map[string]any) []string

PatternsFor returns the full exclusion pattern list for a project: the defaults plus its gen.exclude entries. config is a loaded selfdoc.json.

#Match

func Match(name, pat string) bool

Match reports whether name matches the shell pattern pat, reproducing Python's fnmatch.fnmatch on a POSIX filesystem -- which is what every exclusion pattern in the fleet was written against, and which path/filepath.Match does NOT reproduce.

The whole name must match. The syntax:

- "" matches any run of characters, INCLUDING "/" -- the one difference from filepath.Match that changes real answers, since "_test.*" has to reach a file at any depth of a relative path. - "?" matches one character, again including "/". - "[seq]" matches one character in seq and "[!seq]" one not in seq. A "]" first in the set is that character; a "-" first or last is that character; "x-y" is the inclusive range, and a reversed range matches nothing. An unterminated "[" is the literal character. - Nothing quotes a metacharacter, exactly as Python documents.

Matching is case-sensitive: Python case-normalizes through os.path.normcase, which is the identity on POSIX.