cmd/docsgen/main.go
Source
- Package:
main - File:
cmd/docsgen/main.go - GitHub: https://github.com/theroutercompany/api_router/blob/main/cmd/docsgen/main.go
Overview
What:
Generates "Annotated Source" documentation pages for Go files.
Each generated page includes:
- source metadata (package, file path, GitHub link)
- rendered declaration blocks (imports, const/var/type) with line numbers
- per-symbol "What / Why / How" commentary (loaded from YAML annotations)
- per-function statement walkthroughs (including nested blocks and inline closures)
Why:
The gateway codebase is small enough to read, but large enough that intent and invariants can be lost during onboarding or refactors.
This generator exists to:
- keep docs synchronized with source (structure/snippets are AST-driven)
- keep intent explanations editable (human text in YAML)
- enable "line-by-line" onboarding without manually maintaining huge MDX files
How:
For each input Go file, the generator:
- Parses the file with
go/parserinto an AST. - Extracts declaration blocks and function/method declarations.
- Loads per-file annotations from
docs/annotations/<path>.yaml. - Renders an MDX page under
docs/docs/annotated/<path>.mdxwith syntax-highlighted Go snippets. - Optionally writes/refreshes YAML stubs (
-init-annotations) to keep the symbol list current.
Notes:
The rendered MDX is intentionally treated as build output: edit YAML, re-run docsgen, and commit the regenerated MDX.
MDX authoring gotchas:
- Avoid raw
<in prose unless it is inside inline code. - Avoid starting YAML values with backticks (some YAML parsers can be finicky).
Contents
Imports
import block 1
cmd/docsgen/main.go#L3
import (
"bytes"
"errors"
"flag"
"fmt"
"go/ast"
"go/parser"
"go/printer"
"go/token"
"io/fs"
"os"
"path/filepath"
"sort"
"strings"
"gopkg.in/yaml.v3"
)
Types
type block 1
cmd/docsgen/main.go#L21
type annotationText struct {
What string `yaml:"what"`
How string `yaml:"how"`
Why string `yaml:"why"`
Notes string `yaml:"notes"`
}
annotationText
What: Holds the human-authored explanation fields for a symbol or file overview.
Why: Separates intent-focused prose from the rendered MDX, making documentation maintainable and reviewable.
How: Loaded from YAML and rendered into MDX by writeWhatHowWhy.
type block 2
cmd/docsgen/main.go#L28
type fileAnnotations struct {
File string `yaml:"file"`
Title string `yaml:"title"`
Overview annotationText `yaml:"overview"`
Symbols map[string]annotationText `yaml:"symbols"`
}
fileAnnotations
What: Parsed representation of a per-source-file annotation YAML document.
Why: Allows commentary to be associated with stable symbol IDs independent of line movements or formatting changes.
How: Contains a file path, title, overview text, and a map of symbol IDs to annotationText.
type block 3
cmd/docsgen/main.go#L35
type symbolEntry struct {
ID string
Heading string
}
symbolEntry
What: Minimal representation of a declared symbol used to build the per-block index.
Why: Allows the generator to attach YAML commentary using stable IDs without duplicating full AST structures.
How: Stores the stable symbol ID and the human-friendly heading used in MDX.
type block 4
cmd/docsgen/main.go#L40
type declBlock struct {
Label string
Kind string
StartLine int
Snippet string
Symbols []symbolEntry
}
declBlock
What: Represents one top-level declaration block (imports/const/var/type) for rendering.
Why: Go groups declarations; rendering them as blocks preserves source structure and reduces duplication.
How: Stores the section label, starting line, original snippet, and derived symbol IDs for the block.
type block 5
cmd/docsgen/main.go#L48
type funcEntry struct {
ID string
Heading string
StartLine int
Snippet string
Steps []walkStep
}
funcEntry
What: Represents a single function or method section in the rendered docs.
Why: Bundles stable identity, a source snippet, and walkthrough steps so rendering stays straightforward.
How: Built by extractFuncs and rendered under "Functions and Methods".
type block 6
cmd/docsgen/main.go#L56
type walkStep struct {
StartLine int
Code string
What string
Why string
How string
Children []walkStep
}
walkStep
What: One node in the statement walkthrough tree (possibly with nested children).
Why: Nested control flow needs nested documentation to avoid flattening complex behavior into an unreadable list.
How: Captures line number, condensed code preview, What/Why/How strings, and recursively nested steps.
type block 7
cmd/docsgen/main.go#L65
type walkthroughConfig struct {
Enabled bool
MaxDepth int
MaxSteps int
}
walkthroughConfig
What: Controls whether walkthroughs are generated and how deep/large they are.
Why: Some functions are large; limits keep docs readable and builds fast while still allowing deeper output when needed.
How: Passed through extraction helpers and enforced by walkStmt/extractWalkthroughSteps.
type block 8
cmd/docsgen/main.go#L71
type fileDoc struct {
SrcPath string
OutPath string
AnnotationPath string
Title string
PackageName string
Overview annotationText
Blocks []declBlock
Funcs []funcEntry
}
fileDoc
What: In-memory model of everything needed to render one annotated MDX page.
Why: Keeps extraction (AST/source) separate from rendering (MDX) and makes the generator easier to evolve.
How: Populated by generateFile from parsed AST and annotation YAML, then consumed by render.
type block 9
cmd/docsgen/main.go#L82
type relatedLink struct {
Label string
DocID string
}
relatedLink
What: Declare type relatedLink.
Why: Centralizes behavior and avoids duplication in call sites.
How: See the Go snippet and the source link for behavior and usage.
type block 10
cmd/docsgen/main.go#L87
type relatedSection struct {
Title string
Links []relatedLink
}
relatedSection
What: Declare type relatedSection.
Why: Centralizes behavior and avoids duplication in call sites.
How: See the Go snippet and the source link for behavior and usage.
Functions and Methods
countWalkSteps
What: Declare func countWalkSteps.
Why: Centralizes behavior and avoids duplication in call sites.
How: See the Go snippet and the source link for behavior and usage.
cmd/docsgen/main.go#L92
func countWalkSteps(steps []walkStep) int {
total := 0
for _, step := range steps {
total++
if len(step.Children) > 0 {
total += countWalkSteps(step.Children)
}
}
return total
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L93:
total := 0- What: Defines total.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L94:
for _, step := range steps { total++ if len(step.Children) > 0 { total += countWalkSteps(step.Children) } }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L95:
total++- What: Updates a counter.
- Why: Maintains an index or tally used by subsequent logic.
- How: Executes an increment/decrement statement.
- L96:
if len(step.Children) > 0 { total += countWalkSteps(step.Children) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L97:
total += countWalkSteps(step.Children)- What: Assigns total.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L97:
- L95:
- L100:
return total- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
main
What: CLI entrypoint that wires flags and drives per-file generation.
Why: Provides a simple "regenerate all docs" workflow while still allowing one-off runs on specific files.
How: Parses flags, chooses either the curated core list or explicit file args, and runs generateFile while collecting errors.
cmd/docsgen/main.go#L103
func main() {
var (
repoRoot = flag.String("repo", ".", "repo root")
outDir = flag.String("out", "docs/docs/annotated", "output directory for generated mdx files")
annotationDir = flag.String("annotations", "docs/annotations", "directory for per-file annotation yaml")
githubBase = flag.String("github-base", "https://github.com/theroutercompany/api_router/blob/main/", "base URL for source links")
initAnn = flag.Bool("init-annotations", false, "create/update annotation yaml stubs for the generated files")
walkthrough = flag.Bool("walkthrough", true, "include statement-by-statement walkthroughs for functions/methods")
walkMaxDepth = flag.Int("walkthrough-max-depth", 6, "maximum nesting depth for walkthrough output")
walkMaxSteps = flag.Int("walkthrough-max-steps", 500, "maximum number of walkthrough steps per function/method")
)
flag.Parse()
files := coreFiles()
if len(flag.Args()) > 0 {
files = flag.Args()
}
var errs []error
walkCfg := walkthroughConfig{
Enabled: *walkthrough,
MaxDepth: *walkMaxDepth,
MaxSteps: *walkMaxSteps,
}
for _, rel := range files {
if err := generateFile(*repoRoot, *outDir, *annotationDir, *githubBase, rel, *initAnn, walkCfg); err != nil {
errs = append(errs, err)
}
}
if len(errs) > 0 {
for _, err := range errs {
fmt.Fprintf(os.Stderr, "docsgen error: %v\n", err)
}
os.Exit(1)
}
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L104:
var ( repoRoot = flag.String("repo", ".", "repo root") outDir = flag.String("out", "docs/docs/annotated", "output directory for generated m…- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L114:
flag.Parse()- What: Calls flag.Parse.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L116:
files := coreFiles()- What: Defines files.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L117:
if len(flag.Args()) > 0 { files = flag.Args() }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L118:
files = flag.Args()- What: Assigns files.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L118:
- L121:
var errs []error- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L122:
walkCfg := walkthroughConfig{ Enabled: *walkthrough, MaxDepth: *walkMaxDepth, MaxSteps: *walkMaxSteps, }- What: Defines walkCfg.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L127:
for _, rel := range files { if err := generateFile(*repoRoot, *outDir, *annotationDir, *githubBase, rel, *initAnn, walkCfg); err != nil { e…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L128:
if err := generateFile(*repoRoot, *outDir, *annotationDir, *githubBase, rel, *initAnn, walkCfg); err != nil { errs = append(errs, err) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L128:
err := generateFile(*repoRoot, *outDir, *annotationDir, *githubBase, rel, *initAnn, walkCfg)- What: Defines err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L129:
errs = append(errs, err)- What: Assigns errs.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L128:
- L128:
- L132:
if len(errs) > 0 { for _, err := range errs { fmt.Fprintf(os.Stderr, "docsgen error: %v\n", err) } os.Exit(1) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L133:
for _, err := range errs { fmt.Fprintf(os.Stderr, "docsgen error: %v\n", err) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L134:
fmt.Fprintf(os.Stderr, "docsgen error: %v\n", err)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L134:
- L136:
os.Exit(1)- What: Calls os.Exit.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L133:
coreFiles
What: Returns the curated list of Go files that the docs site treats as the "core" reading path.
Why: Keeps the annotated source section focused on primary entrypoints and runtime packages rather than every incidental file in the repo.
How: Returns a static slice of repo-relative paths; passing explicit CLI args overrides this list.
cmd/docsgen/main.go#L140
func coreFiles() []string {
return []string{
"cmd/apigw/main.go",
"cmd/docsgen/main.go",
"cmd/gateway/main.go",
"cmd/openapi/main.go",
"cmd/shadowdiff/main.go",
"internal/openapi/service.go",
"internal/platform/health/health.go",
"internal/service/placeholder.go",
"internal/shadowdiff/config.go",
"internal/shadowdiff/diff.go",
"internal/shadowdiff/fixture.go",
"internal/shadowdiff/normalize.go",
"examples/basic/main.go",
"pkg/gateway/auth/authenticator.go",
"pkg/gateway/config/config.go",
"pkg/gateway/daemon/daemon.go",
"pkg/gateway/metrics/registry.go",
"pkg/gateway/problem/problem.go",
"pkg/gateway/proxy/reverse_proxy.go",
"pkg/gateway/proxy/testdata/graphql_stream_server.go",
"pkg/gateway/proxy/testdata/sse_server.go",
"pkg/gateway/runtime/runtime.go",
"pkg/gateway/server/middleware/middleware.go",
"pkg/gateway/server/protocol_metrics.go",
"pkg/gateway/server/ratelimiter.go",
"pkg/gateway/server/request_metadata.go",
"pkg/gateway/server/server.go",
"pkg/gateway/webhook/handler.go",
"pkg/log/logger.go",
}
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L141:
return []string{ "cmd/apigw/main.go", "cmd/docsgen/main.go", "cmd/gateway/main.go", "cmd/openapi/main.go", "cmd/shadowdiff/main.go", "inter…- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
generateFile
What: Generates a single annotated MDX page for one repo-relative Go source file.
Why: Keeps the main loop simple and enables ad-hoc generation by passing file paths as CLI arguments.
How: Reads and parses source, extracts blocks/functions, optionally initializes annotation stubs, loads annotations, renders MDX, and writes output.
cmd/docsgen/main.go#L179
func generateFile(repoRoot, outDir, annotationDir, githubBase, relSrcPath string, initAnnotations bool, walkCfg walkthroughConfig) error {
srcPath := filepath.Join(repoRoot, filepath.Clean(relSrcPath))
srcBytes, err := os.ReadFile(srcPath)
if err != nil {
return fmt.Errorf("read %s: %w", relSrcPath, err)
}
fset := token.NewFileSet()
parsed, err := parser.ParseFile(fset, srcPath, srcBytes, parser.ParseComments)
if err != nil {
return fmt.Errorf("parse %s: %w", relSrcPath, err)
}
annPath := filepath.Join(repoRoot, annotationDir, replaceExt(relSrcPath, ".yaml"))
blocks := extractBlocks(fset, parsed, srcBytes)
funcs := extractFuncs(fset, parsed, srcBytes, walkCfg)
if initAnnotations {
if err := ensureAnnotationFile(annPath, relSrcPath, blocks, funcs); err != nil {
return fmt.Errorf("init annotations %s: %w", annPath, err)
}
}
anns, err := loadAnnotations(annPath)
if err != nil {
return fmt.Errorf("load annotations %s: %w", annPath, err)
}
title := anns.Title
if strings.TrimSpace(title) == "" {
title = relSrcPath
}
outPath := filepath.Join(repoRoot, outDir, replaceExt(relSrcPath, ".mdx"))
doc := fileDoc{
SrcPath: relSrcPath,
OutPath: outPath,
AnnotationPath: filepath.ToSlash(filepath.Join(annotationDir, replaceExt(relSrcPath, ".yaml"))),
Title: title,
PackageName: parsed.Name.Name,
Overview: anns.Overview,
}
doc.Blocks = append(doc.Blocks, blocks...)
doc.Funcs = append(doc.Funcs, funcs...)
sort.SliceStable(doc.Blocks, func(i, j int) bool { return doc.Blocks[i].StartLine < doc.Blocks[j].StartLine })
sort.SliceStable(doc.Funcs, func(i, j int) bool { return doc.Funcs[i].StartLine < doc.Funcs[j].StartLine })
if err := os.MkdirAll(filepath.Dir(outPath), 0o755); err != nil {
return fmt.Errorf("mkdir %s: %w", filepath.Dir(outPath), err)
}
content := render(doc, anns, githubBase)
if err := os.WriteFile(outPath, content, 0o644); err != nil {
return fmt.Errorf("write %s: %w", outPath, err)
}
return nil
}
Walkthrough
Expand walkthrough (39 steps)
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L180:
srcPath := filepath.Join(repoRoot, filepath.Clean(relSrcPath))- What: Defines srcPath.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L181:
srcBytes, err := os.ReadFile(srcPath)- What: Defines srcBytes, err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L182:
if err != nil { return fmt.Errorf("read %s: %w", relSrcPath, err) }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L183:
return fmt.Errorf("read %s: %w", relSrcPath, err)- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L183:
- L186:
fset := token.NewFileSet()- What: Defines fset.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L187:
parsed, err := parser.ParseFile(fset, srcPath, srcBytes, parser.ParseComments)- What: Defines parsed, err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L188:
if err != nil { return fmt.Errorf("parse %s: %w", relSrcPath, err) }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L189:
return fmt.Errorf("parse %s: %w", relSrcPath, err)- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L189:
- L192:
annPath := filepath.Join(repoRoot, annotationDir, replaceExt(relSrcPath, ".yaml"))- What: Defines annPath.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L193:
blocks := extractBlocks(fset, parsed, srcBytes)- What: Defines blocks.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L194:
funcs := extractFuncs(fset, parsed, srcBytes, walkCfg)- What: Defines funcs.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L195:
if initAnnotations { if err := ensureAnnotationFile(annPath, relSrcPath, blocks, funcs); err != nil { return fmt.Errorf("init annotations %…- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L196:
if err := ensureAnnotationFile(annPath, relSrcPath, blocks, funcs); err != nil { return fmt.Errorf("init annotations %s: %w", annPath, err)…- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L196:
err := ensureAnnotationFile(annPath, relSrcPath, blocks, funcs)- What: Defines err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L197:
return fmt.Errorf("init annotations %s: %w", annPath, err)- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L196:
- L196:
- L200:
anns, err := loadAnnotations(annPath)- What: Defines anns, err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L201:
if err != nil { return fmt.Errorf("load annotations %s: %w", annPath, err) }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L202:
return fmt.Errorf("load annotations %s: %w", annPath, err)- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L202:
- L205:
title := anns.Title- What: Defines title.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L206:
if strings.TrimSpace(title) == "" { title = relSrcPath }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L207:
title = relSrcPath- What: Assigns title.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L207:
- L210:
outPath := filepath.Join(repoRoot, outDir, replaceExt(relSrcPath, ".mdx"))- What: Defines outPath.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L211:
doc := fileDoc{ SrcPath: relSrcPath, OutPath: outPath, AnnotationPath: filepath.ToSlash(filepath.Join(annotationDir, replaceExt(relSrcPath,…- What: Defines doc.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L220:
doc.Blocks = append(doc.Blocks, blocks...)- What: Assigns doc.Blocks.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L221:
doc.Funcs = append(doc.Funcs, funcs...)- What: Assigns doc.Funcs.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L223:
sort.SliceStable(doc.Blocks, func(i, j int) bool { return doc.Blocks[i].StartLine < doc.Blocks[j].StartLine })- What: Calls sort.SliceStable.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- Nested steps:
- L223:
func(i, j int) bool { return doc.Blocks[i].StartLine < doc.Blocks[j].StartLine }- What: Defines an inline function (closure).
- Why: Encapsulates callback logic and may capture variables from the surrounding scope.
- How: Declares a
funcliteral and uses it as a value (for example, as an HTTP handler or callback). - Nested steps:
- L223:
return doc.Blocks[i].StartLine < doc.Blocks[j].StartLine- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L223:
- L223:
- L224:
sort.SliceStable(doc.Funcs, func(i, j int) bool { return doc.Funcs[i].StartLine < doc.Funcs[j].StartLine })- What: Calls sort.SliceStable.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- Nested steps:
- L224:
func(i, j int) bool { return doc.Funcs[i].StartLine < doc.Funcs[j].StartLine }- What: Defines an inline function (closure).
- Why: Encapsulates callback logic and may capture variables from the surrounding scope.
- How: Declares a
funcliteral and uses it as a value (for example, as an HTTP handler or callback). - Nested steps:
- L224:
return doc.Funcs[i].StartLine < doc.Funcs[j].StartLine- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L224:
- L224:
- L226:
if err := os.MkdirAll(filepath.Dir(outPath), 0o755); err != nil { return fmt.Errorf("mkdir %s: %w", filepath.Dir(outPath), err) }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L226:
err := os.MkdirAll(filepath.Dir(outPath), 0o755)- What: Defines err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L227:
return fmt.Errorf("mkdir %s: %w", filepath.Dir(outPath), err)- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L226:
- L230:
content := render(doc, anns, githubBase)- What: Defines content.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L231:
if err := os.WriteFile(outPath, content, 0o644); err != nil { return fmt.Errorf("write %s: %w", outPath, err) }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L231:
err := os.WriteFile(outPath, content, 0o644)- What: Defines err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L232:
return fmt.Errorf("write %s: %w", outPath, err)- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L231:
- L234:
return nil- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
loadAnnotations
What: Loads per-file annotation YAML into fileAnnotations.
Why: Human commentary is kept separate from generated output so explanations can be edited without touching the rendered MDX.
How: Reads docs/annotations/<path>.yaml, unmarshals via yaml.v3, and normalizes missing symbols to an empty map.
cmd/docsgen/main.go#L237
func loadAnnotations(path string) (fileAnnotations, error) {
data, err := os.ReadFile(path)
if err != nil {
if errors.Is(err, fs.ErrNotExist) {
return fileAnnotations{Symbols: map[string]annotationText{}}, nil
}
return fileAnnotations{}, err
}
var anns fileAnnotations
if err := yaml.Unmarshal(data, &anns); err != nil {
return fileAnnotations{}, err
}
if anns.Symbols == nil {
anns.Symbols = map[string]annotationText{}
}
return anns, nil
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L238:
data, err := os.ReadFile(path)- What: Defines data, err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L239:
if err != nil { if errors.Is(err, fs.ErrNotExist) { return fileAnnotations{Symbols: map[string]annotationText{}}, nil } return fileAnnotati…- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L240:
if errors.Is(err, fs.ErrNotExist) { return fileAnnotations{Symbols: map[string]annotationText{}}, nil }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L241:
return fileAnnotations{Symbols: map[string]annotationText{}}, nil- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L241:
- L243:
return fileAnnotations{}, err- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L240:
- L245:
var anns fileAnnotations- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L246:
if err := yaml.Unmarshal(data, &anns); err != nil { return fileAnnotations{}, err }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L246:
err := yaml.Unmarshal(data, &anns)- What: Defines err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L247:
return fileAnnotations{}, err- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L246:
- L249:
if anns.Symbols == nil { anns.Symbols = map[string]annotationText{} }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L250:
anns.Symbols = map[string]annotationText{}- What: Assigns anns.Symbols.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L250:
- L252:
return anns, nil- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
replaceExt
What: Replaces the file extension and normalizes paths to forward slashes.
Why: The generator needs stable cross-platform paths for both annotation lookups and MDX output routing.
How: Uses filepath.Ext/strings.TrimSuffix and returns a slash-normalized path with the provided extension.
cmd/docsgen/main.go#L255
func replaceExt(path, ext string) string {
base := strings.TrimSuffix(path, filepath.Ext(path))
return filepath.ToSlash(base) + ext
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L256:
base := strings.TrimSuffix(path, filepath.Ext(path))- What: Defines base.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L257:
return filepath.ToSlash(base) + ext- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
docIDForSrc
What: Declare func docIDForSrc.
Why: Centralizes behavior and avoids duplication in call sites.
How: See the Go snippet and the source link for behavior and usage.
cmd/docsgen/main.go#L260
func docIDForSrc(relSrcPath string) string {
base := strings.TrimSuffix(relSrcPath, filepath.Ext(relSrcPath))
base = filepath.ToSlash(base)
parts := strings.Split(base, "/")
if len(parts) >= 2 {
last := parts[len(parts)-1]
prev := parts[len(parts)-2]
if last == prev {
return "annotated/" + strings.Join(parts[:len(parts)-1], "/") + "/"
}
}
return "annotated/" + base
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L261:
base := strings.TrimSuffix(relSrcPath, filepath.Ext(relSrcPath))- What: Defines base.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L262:
base = filepath.ToSlash(base)- What: Assigns base.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L264:
parts := strings.Split(base, "/")- What: Defines parts.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L265:
if len(parts) >= 2 { last := parts[len(parts)-1] prev := parts[len(parts)-2] if last == prev { return "annotated/" + strings.Join(parts[:le…- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L266:
last := parts[len(parts)-1]- What: Defines last.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L267:
prev := parts[len(parts)-2]- What: Defines prev.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L268:
if last == prev { return "annotated/" + strings.Join(parts[:len(parts)-1], "/") + "/" }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L269:
return "annotated/" + strings.Join(parts[:len(parts)-1], "/") + "/"- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L269:
- L266:
- L272:
return "annotated/" + base- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
linkToDoc
What: Declare func linkToDoc.
Why: Centralizes behavior and avoids duplication in call sites.
How: See the Go snippet and the source link for behavior and usage.
cmd/docsgen/main.go#L275
func linkToDoc(fromDocID string, toDocID string) string {
wantTrailingSlash := strings.HasSuffix(toDocID, "/")
fromDir := filepath.Dir(filepath.FromSlash(fromDocID))
to := filepath.FromSlash(toDocID)
rel, err := filepath.Rel(fromDir, to)
if err != nil {
out := filepath.ToSlash(toDocID)
if wantTrailingSlash && !strings.HasSuffix(out, "/") {
out += "/"
}
return out
}
out := filepath.ToSlash(rel)
if wantTrailingSlash && !strings.HasSuffix(out, "/") {
out += "/"
}
return out
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L276:
wantTrailingSlash := strings.HasSuffix(toDocID, "/")- What: Defines wantTrailingSlash.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L277:
fromDir := filepath.Dir(filepath.FromSlash(fromDocID))- What: Defines fromDir.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L278:
to := filepath.FromSlash(toDocID)- What: Defines to.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L279:
rel, err := filepath.Rel(fromDir, to)- What: Defines rel, err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L280:
if err != nil { out := filepath.ToSlash(toDocID) if wantTrailingSlash && !strings.HasSuffix(out, "/") { out += "/" } return out }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L281:
out := filepath.ToSlash(toDocID)- What: Defines out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L282:
if wantTrailingSlash && !strings.HasSuffix(out, "/") { out += "/" }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L283:
out += "/"- What: Assigns out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L283:
- L285:
return out- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L281:
- L287:
out := filepath.ToSlash(rel)- What: Defines out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L288:
if wantTrailingSlash && !strings.HasSuffix(out, "/") { out += "/" }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L289:
out += "/"- What: Assigns out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L289:
- L291:
return out- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
anchorIDFromSymbolID
What: Declare func anchorIDFromSymbolID.
Why: Centralizes behavior and avoids duplication in call sites.
How: See the Go snippet and the source link for behavior and usage.
cmd/docsgen/main.go#L294
func anchorIDFromSymbolID(symbolID string) string {
s := strings.ToLower(strings.TrimSpace(symbolID))
if s == "" {
return "symbol"
}
var b strings.Builder
b.Grow(len(s))
lastDash := false
for _, r := range s {
isAlnum := (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9')
if isAlnum {
b.WriteRune(r)
lastDash = false
continue
}
if lastDash {
continue
}
b.WriteByte('-')
lastDash = true
}
out := strings.Trim(b.String(), "-")
if out == "" {
return "symbol"
}
return out
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L295:
s := strings.ToLower(strings.TrimSpace(symbolID))- What: Defines s.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L296:
if s == "" { return "symbol" }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L297:
return "symbol"- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L297:
- L299:
var b strings.Builder- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L300:
b.Grow(len(s))- What: Calls b.Grow.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L301:
lastDash := false- What: Defines lastDash.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L302:
for _, r := range s { isAlnum := (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') if isAlnum { b.WriteRune(r) lastDash = false continue } i…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L303:
isAlnum := (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9')- What: Defines isAlnum.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L304:
if isAlnum { b.WriteRune(r) lastDash = false continue }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L305:
b.WriteRune(r)- What: Calls b.WriteRune.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L306:
lastDash = false- What: Assigns lastDash.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L307:
continue- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L305:
- L309:
if lastDash { continue }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L310:
continue- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L310:
- L312:
b.WriteByte('-')- What: Calls b.WriteByte.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L313:
lastDash = true- What: Assigns lastDash.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L303:
- L315:
out := strings.Trim(b.String(), "-")- What: Defines out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L316:
if out == "" { return "symbol" }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L317:
return "symbol"- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L317:
- L319:
return out- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
extractBlocks
What: Extracts top-level declaration blocks from a Go file (imports/const/var/type).
Why: The docs show declarations grouped by kind with the original source formatting and line numbers.
How: Walks file.Decls, filters *ast.GenDecl, and converts each supported token kind into a declBlock.
cmd/docsgen/main.go#L322
func extractBlocks(fset *token.FileSet, file *ast.File, src []byte) []declBlock {
var blocks []declBlock
for _, decl := range file.Decls {
gen, ok := decl.(*ast.GenDecl)
if !ok {
continue
}
switch gen.Tok {
case token.IMPORT:
blocks = append(blocks, buildGenDeclBlock(fset, gen, src, "Imports", "import"))
case token.CONST:
blocks = append(blocks, buildGenDeclBlock(fset, gen, src, "Constants", "const"))
case token.VAR:
blocks = append(blocks, buildGenDeclBlock(fset, gen, src, "Variables", "var"))
case token.TYPE:
blocks = append(blocks, buildGenDeclBlock(fset, gen, src, "Types", "type"))
}
}
return blocks
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L323:
var blocks []declBlock- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L324:
for _, decl := range file.Decls { gen, ok := decl.(*ast.GenDecl) if !ok { continue } switch gen.Tok { case token.IMPORT: blocks = append(bl…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L325:
gen, ok := decl.(*ast.GenDecl)- What: Defines gen, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L326:
if !ok { continue }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L327:
continue- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L327:
- L329:
switch gen.Tok { case token.IMPORT: blocks = append(blocks, buildGenDeclBlock(fset, gen, src, "Imports", "import")) case token.CONST: block…- What: Selects a branch from multiple cases.
- Why: Keeps multi-case branching readable and explicit.
- How: Evaluates the switch expression and executes the first matching case.
- Nested steps:
- L330:
case token.IMPORT:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L331:
blocks = append(blocks, buildGenDeclBlock(fset, gen, src, "Imports", "import"))- What: Assigns blocks.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L331:
- L332:
case token.CONST:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L333:
blocks = append(blocks, buildGenDeclBlock(fset, gen, src, "Constants", "const"))- What: Assigns blocks.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L333:
- L334:
case token.VAR:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L335:
blocks = append(blocks, buildGenDeclBlock(fset, gen, src, "Variables", "var"))- What: Assigns blocks.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L335:
- L336:
case token.TYPE:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L337:
blocks = append(blocks, buildGenDeclBlock(fset, gen, src, "Types", "type"))- What: Assigns blocks.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L337:
- L330:
- L325:
- L340:
return blocks- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
buildGenDeclBlock
What: Builds a declBlock (snippet + symbol IDs) from a Go GenDecl (imports/const/var/type).
Why: Declaration blocks are the backbone of the page's symbol index and let readers jump directly to the relevant type/constant/variable.
How: Slices the original source for a faithful snippet, then derives stable symbol IDs from ValueSpec and TypeSpec nodes.
cmd/docsgen/main.go#L343
func buildGenDeclBlock(fset *token.FileSet, gen *ast.GenDecl, src []byte, sectionLabel, kind string) declBlock {
startLine := fset.Position(gen.Pos()).Line
snippet := sliceSource(fset, src, gen.Pos(), gen.End())
var symbols []symbolEntry
for _, spec := range gen.Specs {
switch s := spec.(type) {
case *ast.ValueSpec:
for _, name := range s.Names {
id := fmt.Sprintf("%s %s", kind, name.Name)
symbols = append(symbols, symbolEntry{
ID: id,
Heading: fmt.Sprintf("`%s`", name.Name),
})
}
case *ast.TypeSpec:
id := fmt.Sprintf("%s %s", kind, s.Name.Name)
symbols = append(symbols, symbolEntry{
ID: id,
Heading: fmt.Sprintf("`%s`", s.Name.Name),
})
}
}
return declBlock{
Label: sectionLabel,
Kind: kind,
StartLine: startLine,
Snippet: snippet,
Symbols: symbols,
}
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L344:
startLine := fset.Position(gen.Pos()).Line- What: Defines startLine.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L345:
snippet := sliceSource(fset, src, gen.Pos(), gen.End())- What: Defines snippet.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L347:
var symbols []symbolEntry- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L348:
for _, spec := range gen.Specs { switch s := spec.(type) { case *ast.ValueSpec: for _, name := range s.Names { id := fmt.Sprintf("%s %s", k…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L349:
switch s := spec.(type) { case *ast.ValueSpec: for _, name := range s.Names { id := fmt.Sprintf("%s %s", kind, name.Name) symbols = append(…- What: Selects a branch based on dynamic type.
- Why: Handles multiple concrete types cleanly.
- How: Executes a type switch statement.
- Nested steps:
- L349:
s := spec.(type)- What: Defines s.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L350:
case *ast.ValueSpec:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L351:
for _, name := range s.Names { id := fmt.Sprintf("%s %s", kind, name.Name) symbols = append(symbols, symbolEntry{ ID: id, Heading: fmt.Spri…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L352:
id := fmt.Sprintf("%s %s", kind, name.Name)- What: Defines id.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L353:
symbols = append(symbols, symbolEntry{ ID: id, Heading: fmt.Sprintf("`%s`", name.Name), })- What: Assigns symbols.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L352:
- L351:
- L358:
case *ast.TypeSpec:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L359:
id := fmt.Sprintf("%s %s", kind, s.Name.Name)- What: Defines id.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L360:
symbols = append(symbols, symbolEntry{ ID: id, Heading: fmt.Sprintf("`%s`", s.Name.Name), })- What: Assigns symbols.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L359:
- L349:
- L349:
- L367:
return declBlock{ Label: sectionLabel, Kind: kind, StartLine: startLine, Snippet: snippet, Symbols: symbols, }- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
extractFuncs
What: Extracts top-level functions and methods into funcEntry records.
Why: Functions/methods are the main behavioral units readers look for when onboarding or debugging.
How: Iterates *ast.FuncDecl nodes, computes stable IDs for functions vs methods, slices source snippets, and optionally attaches walkthrough steps.
cmd/docsgen/main.go#L376
func extractFuncs(fset *token.FileSet, file *ast.File, src []byte, walkCfg walkthroughConfig) []funcEntry {
var entries []funcEntry
for _, decl := range file.Decls {
fn, ok := decl.(*ast.FuncDecl)
if !ok {
continue
}
startLine := fset.Position(fn.Pos()).Line
snippet := sliceSource(fset, src, fn.Pos(), fn.End())
steps := []walkStep(nil)
if walkCfg.Enabled {
steps = extractWalkthroughSteps(fset, src, fn, walkCfg)
}
id := fmt.Sprintf("func %s", fn.Name.Name)
heading := fmt.Sprintf("`%s`", fn.Name.Name)
if fn.Recv != nil && len(fn.Recv.List) > 0 {
recv := receiverTypeString(fset, fn.Recv.List[0].Type)
id = fmt.Sprintf("method (%s).%s", recv, fn.Name.Name)
heading = fmt.Sprintf("`(%s).%s`", recv, fn.Name.Name)
}
entries = append(entries, funcEntry{
ID: id,
Heading: heading,
StartLine: startLine,
Snippet: snippet,
Steps: steps,
})
}
return entries
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L377:
var entries []funcEntry- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L378:
for _, decl := range file.Decls { fn, ok := decl.(*ast.FuncDecl) if !ok { continue } startLine := fset.Position(fn.Pos()).Line snippet := s…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L379:
fn, ok := decl.(*ast.FuncDecl)- What: Defines fn, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L380:
if !ok { continue }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L381:
continue- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L381:
- L384:
startLine := fset.Position(fn.Pos()).Line- What: Defines startLine.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L385:
snippet := sliceSource(fset, src, fn.Pos(), fn.End())- What: Defines snippet.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L386:
steps := []walkStep(nil)- What: Defines steps.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L387:
if walkCfg.Enabled { steps = extractWalkthroughSteps(fset, src, fn, walkCfg) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L388:
steps = extractWalkthroughSteps(fset, src, fn, walkCfg)- What: Assigns steps.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L388:
- L391:
id := fmt.Sprintf("func %s", fn.Name.Name)- What: Defines id.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L392:
heading := fmt.Sprintf("`%s`", fn.Name.Name)- What: Defines heading.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L393:
if fn.Recv != nil && len(fn.Recv.List) > 0 { recv := receiverTypeString(fset, fn.Recv.List[0].Type) id = fmt.Sprintf("method (%s).%s", recv…- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L394:
recv := receiverTypeString(fset, fn.Recv.List[0].Type)- What: Defines recv.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L395:
id = fmt.Sprintf("method (%s).%s", recv, fn.Name.Name)- What: Assigns id.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L396:
heading = fmt.Sprintf("`(%s).%s`", recv, fn.Name.Name)- What: Assigns heading.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L394:
- L399:
entries = append(entries, funcEntry{ ID: id, Heading: heading, StartLine: startLine, Snippet: snippet, Steps: steps, })- What: Assigns entries.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L379:
- L407:
return entries- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
extractWalkthroughSteps
What: Produces a statement-by-statement walkthrough for a function body.
Why: Implements the "line-by-line" requirement by explaining what each statement does and how it fits into the function logic.
How: Walks the function's top-level statements with walkStmt, respecting MaxSteps and emitting a truncation sentinel when exceeded.
cmd/docsgen/main.go#L410
func extractWalkthroughSteps(fset *token.FileSet, src []byte, fn *ast.FuncDecl, cfg walkthroughConfig) []walkStep {
if fn == nil || fn.Body == nil || len(fn.Body.List) == 0 || cfg.MaxSteps <= 0 {
return nil
}
steps := make([]walkStep, 0, len(fn.Body.List))
count := 0
for _, stmt := range fn.Body.List {
if stmt == nil || count >= cfg.MaxSteps {
break
}
step, ok := walkStmt(fset, src, stmt, 0, cfg, &count)
if ok {
steps = append(steps, step)
}
}
if count >= cfg.MaxSteps {
steps = append(steps, walkStep{
StartLine: fset.Position(fn.End()).Line,
Code: "(walkthrough truncated)",
What: "Walkthrough output was truncated.",
Why: "Keeps pages readable and avoids generating excessively large MDX output by default.",
How: "Re-run docsgen with a higher `-walkthrough-max-steps` value to include more steps.",
})
}
return steps
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L411:
if fn == nil || fn.Body == nil || len(fn.Body.List) == 0 || cfg.MaxSteps <= 0 { return nil }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L412:
return nil- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L412:
- L415:
steps := make([]walkStep, 0, len(fn.Body.List))- What: Defines steps.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L416:
count := 0- What: Defines count.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L417:
for _, stmt := range fn.Body.List { if stmt == nil || count >= cfg.MaxSteps { break } step, ok := walkStmt(fset, src, stmt, 0, cfg, &count)…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L418:
if stmt == nil || count >= cfg.MaxSteps { break }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L419:
break- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L419:
- L421:
step, ok := walkStmt(fset, src, stmt, 0, cfg, &count)- What: Defines step, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L422:
if ok { steps = append(steps, step) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L423:
steps = append(steps, step)- What: Assigns steps.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L423:
- L418:
- L426:
if count >= cfg.MaxSteps { steps = append(steps, walkStep{ StartLine: fset.Position(fn.End()).Line, Code: "(walkthrough truncated)", What: …- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L427:
steps = append(steps, walkStep{ StartLine: fset.Position(fn.End()).Line, Code: "(walkthrough truncated)", What: "Walkthrough output was tru…- What: Assigns steps.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L427:
- L435:
return steps- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
walkStmt
What: Converts a statement into a walkthrough step and recursively collects nested steps.
Why: Implements structured, nested walkthrough output that matches how humans mentally model control flow.
How: Describes the statement, increments a shared step counter, and then dives into child blocks/branches (if/for/switch/select) and embedded closures.
cmd/docsgen/main.go#L438
func walkStmt(fset *token.FileSet, src []byte, stmt ast.Stmt, depth int, cfg walkthroughConfig, count *int) (walkStep, bool) {
if stmt == nil || count == nil || *count >= cfg.MaxSteps {
return walkStep{}, false
}
startLine := fset.Position(stmt.Pos()).Line
code := condenseSnippet(sliceSource(fset, src, stmt.Pos(), stmt.End()))
what, why, how := describeStmt(fset, stmt)
step := walkStep{
StartLine: startLine,
Code: code,
What: what,
Why: why,
How: how,
}
*count++
if *count >= cfg.MaxSteps || depth >= cfg.MaxDepth {
return step, true
}
appendChild := func(child walkStep) {
if *count >= cfg.MaxSteps {
return
}
step.Children = append(step.Children, child)
}
appendChildren := func(children []walkStep) {
for _, child := range children {
if *count >= cfg.MaxSteps {
return
}
step.Children = append(step.Children, child)
}
}
switch s := stmt.(type) {
case *ast.BlockStmt:
appendChildren(walkStmtList(fset, src, s.List, depth+1, cfg, count))
return step, true
case *ast.LabeledStmt:
if s.Stmt != nil {
if child, ok := walkStmt(fset, src, s.Stmt, depth+1, cfg, count); ok {
appendChild(child)
}
}
return step, true
case *ast.IfStmt:
if s.Init != nil {
if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok {
appendChild(child)
}
}
appendChildren(walkStmtList(fset, src, s.Body.List, depth+1, cfg, count))
switch elseNode := s.Else.(type) {
case *ast.BlockStmt:
appendChildren(walkStmtList(fset, src, elseNode.List, depth+1, cfg, count))
case ast.Stmt:
if child, ok := walkStmt(fset, src, elseNode, depth+1, cfg, count); ok {
appendChild(child)
}
}
appendChildren(walkFuncLitsFromExpr(fset, src, s.Cond, depth+1, cfg, count))
return step, true
case *ast.ForStmt:
if s.Init != nil {
if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok {
appendChild(child)
}
}
if s.Post != nil {
if child, ok := walkStmt(fset, src, s.Post, depth+1, cfg, count); ok {
appendChild(child)
}
}
appendChildren(walkStmtList(fset, src, s.Body.List, depth+1, cfg, count))
appendChildren(walkFuncLitsFromExpr(fset, src, s.Cond, depth+1, cfg, count))
return step, true
case *ast.RangeStmt:
appendChildren(walkStmtList(fset, src, s.Body.List, depth+1, cfg, count))
appendChildren(walkFuncLitsFromExpr(fset, src, s.X, depth+1, cfg, count))
return step, true
case *ast.SwitchStmt:
if s.Init != nil {
if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok {
appendChild(child)
}
}
appendChildren(walkFuncLitsFromExpr(fset, src, s.Tag, depth+1, cfg, count))
for _, raw := range s.Body.List {
cc, ok := raw.(*ast.CaseClause)
if !ok || *count >= cfg.MaxSteps {
break
}
caseStep, ok := walkCaseClause(fset, src, cc, depth+1, cfg, count)
if ok {
appendChild(caseStep)
}
}
return step, true
case *ast.TypeSwitchStmt:
if s.Init != nil {
if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok {
appendChild(child)
}
}
if s.Assign != nil {
if child, ok := walkStmt(fset, src, s.Assign, depth+1, cfg, count); ok {
appendChild(child)
}
}
for _, raw := range s.Body.List {
cc, ok := raw.(*ast.CaseClause)
if !ok || *count >= cfg.MaxSteps {
break
}
caseStep, ok := walkCaseClause(fset, src, cc, depth+1, cfg, count)
if ok {
appendChild(caseStep)
}
}
return step, true
case *ast.SelectStmt:
for _, raw := range s.Body.List {
cl, ok := raw.(*ast.CommClause)
if !ok || *count >= cfg.MaxSteps {
break
}
caseStep, ok := walkCommClause(fset, src, cl, depth+1, cfg, count)
if ok {
appendChild(caseStep)
}
}
return step, true
case *ast.AssignStmt:
for _, expr := range s.Rhs {
appendChildren(walkFuncLitsFromExpr(fset, src, expr, depth+1, cfg, count))
}
return step, true
case *ast.ReturnStmt:
for _, expr := range s.Results {
appendChildren(walkFuncLitsFromExpr(fset, src, expr, depth+1, cfg, count))
}
return step, true
case *ast.ExprStmt:
appendChildren(walkFuncLitsFromExpr(fset, src, s.X, depth+1, cfg, count))
return step, true
case *ast.GoStmt:
if s.Call != nil {
appendChildren(walkFuncLitsFromExpr(fset, src, s.Call, depth+1, cfg, count))
}
return step, true
case *ast.DeferStmt:
if s.Call != nil {
appendChildren(walkFuncLitsFromExpr(fset, src, s.Call, depth+1, cfg, count))
}
return step, true
default:
return step, true
}
}
Walkthrough
Expand walkthrough (124 steps)
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L439:
if stmt == nil || count == nil || *count >= cfg.MaxSteps { return walkStep{}, false }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L440:
return walkStep{}, false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L440:
- L443:
startLine := fset.Position(stmt.Pos()).Line- What: Defines startLine.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L444:
code := condenseSnippet(sliceSource(fset, src, stmt.Pos(), stmt.End()))- What: Defines code.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L445:
what, why, how := describeStmt(fset, stmt)- What: Defines what, why, how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L446:
step := walkStep{ StartLine: startLine, Code: code, What: what, Why: why, How: how, }- What: Defines step.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L453:
*count++- What: Updates a counter.
- Why: Maintains an index or tally used by subsequent logic.
- How: Executes an increment/decrement statement.
- L454:
if *count >= cfg.MaxSteps || depth >= cfg.MaxDepth { return step, true }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L455:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L455:
- L458:
appendChild := func(child walkStep) { if *count >= cfg.MaxSteps { return } step.Children = append(step.Children, child) }- What: Defines appendChild.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- Nested steps:
- L458:
func(child walkStep) { if *count >= cfg.MaxSteps { return } step.Children = append(step.Children, child) }- What: Defines an inline function (closure).
- Why: Encapsulates callback logic and may capture variables from the surrounding scope.
- How: Declares a
funcliteral and uses it as a value (for example, as an HTTP handler or callback). - Nested steps:
- L459:
if *count >= cfg.MaxSteps { return }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L460:
return- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L460:
- L462:
step.Children = append(step.Children, child)- What: Assigns step.Children.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L459:
- L458:
- L464:
appendChildren := func(children []walkStep) { for _, child := range children { if *count >= cfg.MaxSteps { return } step.Children = append(…- What: Defines appendChildren.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- Nested steps:
- L464:
func(children []walkStep) { for _, child := range children { if *count >= cfg.MaxSteps { return } step.Children = append(step.Children, chi…- What: Defines an inline function (closure).
- Why: Encapsulates callback logic and may capture variables from the surrounding scope.
- How: Declares a
funcliteral and uses it as a value (for example, as an HTTP handler or callback). - Nested steps:
- L465:
for _, child := range children { if *count >= cfg.MaxSteps { return } step.Children = append(step.Children, child) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L466:
if *count >= cfg.MaxSteps { return }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L467:
return- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L467:
- L469:
step.Children = append(step.Children, child)- What: Assigns step.Children.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L466:
- L465:
- L464:
- L473:
switch s := stmt.(type) { case *ast.BlockStmt: appendChildren(walkStmtList(fset, src, s.List, depth+1, cfg, count)) return step, true case …- What: Selects a branch based on dynamic type.
- Why: Handles multiple concrete types cleanly.
- How: Executes a type switch statement.
- Nested steps:
- L473:
s := stmt.(type)- What: Defines s.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L474:
case *ast.BlockStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L475:
appendChildren(walkStmtList(fset, src, s.List, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L476:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L475:
- L478:
case *ast.LabeledStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L479:
if s.Stmt != nil { if child, ok := walkStmt(fset, src, s.Stmt, depth+1, cfg, count); ok { appendChild(child) } }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L480:
if child, ok := walkStmt(fset, src, s.Stmt, depth+1, cfg, count); ok { appendChild(child) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L480:
child, ok := walkStmt(fset, src, s.Stmt, depth+1, cfg, count)- What: Defines child, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L481:
appendChild(child)- What: Calls appendChild.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L480:
- L480:
- L484:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L479:
- L486:
case *ast.IfStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L487:
if s.Init != nil { if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok { appendChild(child) } }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L488:
if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok { appendChild(child) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L488:
child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count)- What: Defines child, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L489:
appendChild(child)- What: Calls appendChild.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L488:
- L488:
- L492:
appendChildren(walkStmtList(fset, src, s.Body.List, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L493:
switch elseNode := s.Else.(type) { case *ast.BlockStmt: appendChildren(walkStmtList(fset, src, elseNode.List, depth+1, cfg, count)) case as…- What: Selects a branch based on dynamic type.
- Why: Handles multiple concrete types cleanly.
- How: Executes a type switch statement.
- Nested steps:
- L493:
elseNode := s.Else.(type)- What: Defines elseNode.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L494:
case *ast.BlockStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L495:
appendChildren(walkStmtList(fset, src, elseNode.List, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L495:
- L496:
case ast.Stmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L497:
if child, ok := walkStmt(fset, src, elseNode, depth+1, cfg, count); ok { appendChild(child) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L497:
child, ok := walkStmt(fset, src, elseNode, depth+1, cfg, count)- What: Defines child, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L498:
appendChild(child)- What: Calls appendChild.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L497:
- L497:
- L493:
- L501:
appendChildren(walkFuncLitsFromExpr(fset, src, s.Cond, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L502:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L487:
- L504:
case *ast.ForStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L505:
if s.Init != nil { if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok { appendChild(child) } }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L506:
if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok { appendChild(child) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L506:
child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count)- What: Defines child, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L507:
appendChild(child)- What: Calls appendChild.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L506:
- L506:
- L510:
if s.Post != nil { if child, ok := walkStmt(fset, src, s.Post, depth+1, cfg, count); ok { appendChild(child) } }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L511:
if child, ok := walkStmt(fset, src, s.Post, depth+1, cfg, count); ok { appendChild(child) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L511:
child, ok := walkStmt(fset, src, s.Post, depth+1, cfg, count)- What: Defines child, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L512:
appendChild(child)- What: Calls appendChild.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L511:
- L511:
- L515:
appendChildren(walkStmtList(fset, src, s.Body.List, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L516:
appendChildren(walkFuncLitsFromExpr(fset, src, s.Cond, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L517:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L505:
- L519:
case *ast.RangeStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L520:
appendChildren(walkStmtList(fset, src, s.Body.List, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L521:
appendChildren(walkFuncLitsFromExpr(fset, src, s.X, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L522:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L520:
- L524:
case *ast.SwitchStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L525:
if s.Init != nil { if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok { appendChild(child) } }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L526:
if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok { appendChild(child) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L526:
child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count)- What: Defines child, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L527:
appendChild(child)- What: Calls appendChild.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L526:
- L526:
- L530:
appendChildren(walkFuncLitsFromExpr(fset, src, s.Tag, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L531:
for _, raw := range s.Body.List { cc, ok := raw.(*ast.CaseClause) if !ok || *count >= cfg.MaxSteps { break } caseStep, ok := walkCaseClause…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L532:
cc, ok := raw.(*ast.CaseClause)- What: Defines cc, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L533:
if !ok || *count >= cfg.MaxSteps { break }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L534:
break- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L534:
- L536:
caseStep, ok := walkCaseClause(fset, src, cc, depth+1, cfg, count)- What: Defines caseStep, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L537:
if ok { appendChild(caseStep) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L538:
appendChild(caseStep)- What: Calls appendChild.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L538:
- L532:
- L541:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L525:
- L543:
case *ast.TypeSwitchStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L544:
if s.Init != nil { if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok { appendChild(child) } }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L545:
if child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count); ok { appendChild(child) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L545:
child, ok := walkStmt(fset, src, s.Init, depth+1, cfg, count)- What: Defines child, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L546:
appendChild(child)- What: Calls appendChild.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L545:
- L545:
- L549:
if s.Assign != nil { if child, ok := walkStmt(fset, src, s.Assign, depth+1, cfg, count); ok { appendChild(child) } }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L550:
if child, ok := walkStmt(fset, src, s.Assign, depth+1, cfg, count); ok { appendChild(child) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L550:
child, ok := walkStmt(fset, src, s.Assign, depth+1, cfg, count)- What: Defines child, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L551:
appendChild(child)- What: Calls appendChild.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L550:
- L550:
- L554:
for _, raw := range s.Body.List { cc, ok := raw.(*ast.CaseClause) if !ok || *count >= cfg.MaxSteps { break } caseStep, ok := walkCaseClause…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L555:
cc, ok := raw.(*ast.CaseClause)- What: Defines cc, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L556:
if !ok || *count >= cfg.MaxSteps { break }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L557:
break- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L557:
- L559:
caseStep, ok := walkCaseClause(fset, src, cc, depth+1, cfg, count)- What: Defines caseStep, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L560:
if ok { appendChild(caseStep) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L561:
appendChild(caseStep)- What: Calls appendChild.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L561:
- L555:
- L564:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L544:
- L566:
case *ast.SelectStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L567:
for _, raw := range s.Body.List { cl, ok := raw.(*ast.CommClause) if !ok || *count >= cfg.MaxSteps { break } caseStep, ok := walkCommClause…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L568:
cl, ok := raw.(*ast.CommClause)- What: Defines cl, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L569:
if !ok || *count >= cfg.MaxSteps { break }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L570:
break- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L570:
- L572:
caseStep, ok := walkCommClause(fset, src, cl, depth+1, cfg, count)- What: Defines caseStep, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L573:
if ok { appendChild(caseStep) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L574:
appendChild(caseStep)- What: Calls appendChild.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L574:
- L568:
- L577:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L567:
- L579:
case *ast.AssignStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L580:
for _, expr := range s.Rhs { appendChildren(walkFuncLitsFromExpr(fset, src, expr, depth+1, cfg, count)) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L581:
appendChildren(walkFuncLitsFromExpr(fset, src, expr, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L581:
- L583:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L580:
- L585:
case *ast.ReturnStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L586:
for _, expr := range s.Results { appendChildren(walkFuncLitsFromExpr(fset, src, expr, depth+1, cfg, count)) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L587:
appendChildren(walkFuncLitsFromExpr(fset, src, expr, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L587:
- L589:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L586:
- L591:
case *ast.ExprStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L592:
appendChildren(walkFuncLitsFromExpr(fset, src, s.X, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L593:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L592:
- L595:
case *ast.GoStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L596:
if s.Call != nil { appendChildren(walkFuncLitsFromExpr(fset, src, s.Call, depth+1, cfg, count)) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L597:
appendChildren(walkFuncLitsFromExpr(fset, src, s.Call, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L597:
- L599:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L596:
- L601:
case *ast.DeferStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L602:
if s.Call != nil { appendChildren(walkFuncLitsFromExpr(fset, src, s.Call, depth+1, cfg, count)) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L603:
appendChildren(walkFuncLitsFromExpr(fset, src, s.Call, depth+1, cfg, count))- What: Calls appendChildren.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L603:
- L605:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L602:
- L607:
default:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L608:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L608:
- L473:
walkStmtList
What: Walks a list of statements into walkthrough steps.
Why: Common helper used for all block-like constructs to keep recursion logic consistent.
How: Iterates the list, calling walkStmt while respecting max-steps limits.
cmd/docsgen/main.go#L612
func walkStmtList(fset *token.FileSet, src []byte, list []ast.Stmt, depth int, cfg walkthroughConfig, count *int) []walkStep {
if len(list) == 0 || count == nil || *count >= cfg.MaxSteps {
return nil
}
out := make([]walkStep, 0, len(list))
for _, stmt := range list {
if stmt == nil || *count >= cfg.MaxSteps {
break
}
step, ok := walkStmt(fset, src, stmt, depth, cfg, count)
if ok {
out = append(out, step)
}
}
return out
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L613:
if len(list) == 0 || count == nil || *count >= cfg.MaxSteps { return nil }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L614:
return nil- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L614:
- L616:
out := make([]walkStep, 0, len(list))- What: Defines out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L617:
for _, stmt := range list { if stmt == nil || *count >= cfg.MaxSteps { break } step, ok := walkStmt(fset, src, stmt, depth, cfg, count) if …- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L618:
if stmt == nil || *count >= cfg.MaxSteps { break }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L619:
break- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L619:
- L621:
step, ok := walkStmt(fset, src, stmt, depth, cfg, count)- What: Defines step, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L622:
if ok { out = append(out, step) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L623:
out = append(out, step)- What: Assigns out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L623:
- L618:
- L626:
return out- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
walkFuncLitsFromExpr
What: Finds and walks all closures nested inside an expression.
Why: Many statements embed closures in call arguments; without this, walkthroughs would skip important behavior.
How: Extracts *ast.FuncLit values from the expression and wraps each using walkFuncLit.
cmd/docsgen/main.go#L629
func walkFuncLitsFromExpr(fset *token.FileSet, src []byte, expr ast.Expr, depth int, cfg walkthroughConfig, count *int) []walkStep {
if expr == nil || count == nil || *count >= cfg.MaxSteps {
return nil
}
lits := funcLitsInExpr(expr)
if len(lits) == 0 {
return nil
}
out := make([]walkStep, 0, len(lits))
for _, lit := range lits {
if lit == nil || *count >= cfg.MaxSteps {
break
}
step, ok := walkFuncLit(fset, src, lit, depth, cfg, count)
if ok {
out = append(out, step)
}
}
return out
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L630:
if expr == nil || count == nil || *count >= cfg.MaxSteps { return nil }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L631:
return nil- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L631:
- L633:
lits := funcLitsInExpr(expr)- What: Defines lits.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L634:
if len(lits) == 0 { return nil }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L635:
return nil- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L635:
- L637:
out := make([]walkStep, 0, len(lits))- What: Defines out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L638:
for _, lit := range lits { if lit == nil || *count >= cfg.MaxSteps { break } step, ok := walkFuncLit(fset, src, lit, depth, cfg, count) if …- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L639:
if lit == nil || *count >= cfg.MaxSteps { break }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L640:
break- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L640:
- L642:
step, ok := walkFuncLit(fset, src, lit, depth, cfg, count)- What: Defines step, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L643:
if ok { out = append(out, step) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L644:
out = append(out, step)- What: Assigns out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L644:
- L639:
- L647:
return out- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
walkFuncLit
What: Converts an inline function literal into a walkthrough step and walks its body as nested steps.
Why: Closures often contain the "real" behavior in handler-heavy code; including them satisfies the line-by-line documentation goal.
How: Emits a synthetic step for the closure and then recursively walks the closure body if present.
cmd/docsgen/main.go#L650
func walkFuncLit(fset *token.FileSet, src []byte, lit *ast.FuncLit, depth int, cfg walkthroughConfig, count *int) (walkStep, bool) {
if lit == nil || count == nil || *count >= cfg.MaxSteps {
return walkStep{}, false
}
startLine := fset.Position(lit.Pos()).Line
code := condenseSnippet(sliceSource(fset, src, lit.Pos(), lit.End()))
step := walkStep{
StartLine: startLine,
Code: code,
What: "Defines an inline function (closure).",
Why: "Encapsulates callback logic and may capture variables from the surrounding scope.",
How: "Declares a `func` literal and uses it as a value (for example, as an HTTP handler or callback).",
}
*count++
if *count >= cfg.MaxSteps || depth >= cfg.MaxDepth || lit.Body == nil || len(lit.Body.List) == 0 {
return step, true
}
step.Children = append(step.Children, walkStmtList(fset, src, lit.Body.List, depth+1, cfg, count)...)
return step, true
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L651:
if lit == nil || count == nil || *count >= cfg.MaxSteps { return walkStep{}, false }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L652:
return walkStep{}, false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L652:
- L655:
startLine := fset.Position(lit.Pos()).Line- What: Defines startLine.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L656:
code := condenseSnippet(sliceSource(fset, src, lit.Pos(), lit.End()))- What: Defines code.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L657:
step := walkStep{ StartLine: startLine, Code: code, What: "Defines an inline function (closure).", Why: "Encapsulates callback logic and ma…- What: Defines step.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L664:
*count++- What: Updates a counter.
- Why: Maintains an index or tally used by subsequent logic.
- How: Executes an increment/decrement statement.
- L665:
if *count >= cfg.MaxSteps || depth >= cfg.MaxDepth || lit.Body == nil || len(lit.Body.List) == 0 { return step, true }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L666:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L666:
- L669:
step.Children = append(step.Children, walkStmtList(fset, src, lit.Body.List, depth+1, cfg, count)...)- What: Assigns step.Children.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L670:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
walkCaseClause
What: Converts a switch case clause into a walkthrough step (with nested statement children).
Why: Switch bodies often hold substantial logic that should appear in walkthroughs, not as an opaque single statement.
How: Builds a case ...: / default: header, then walks the clause body via walkStmtList respecting depth/step limits.
cmd/docsgen/main.go#L673
func walkCaseClause(fset *token.FileSet, src []byte, clause *ast.CaseClause, depth int, cfg walkthroughConfig, count *int) (walkStep, bool) {
if clause == nil || count == nil || *count >= cfg.MaxSteps {
return walkStep{}, false
}
startLine := fset.Position(clause.Pos()).Line
var head string
if len(clause.List) == 0 {
head = "default:"
} else {
var parts []string
for _, expr := range clause.List {
parts = append(parts, strings.TrimSpace(nodeString(fset, expr)))
}
head = "case " + strings.Join(parts, ", ") + ":"
}
step := walkStep{
StartLine: startLine,
Code: condenseSnippet(head),
What: "Selects a switch case.",
Why: "Makes multi-branch control flow explicit and readable.",
How: "Runs this case body when the switch value matches (or when default is selected).",
}
*count++
if *count >= cfg.MaxSteps || depth >= cfg.MaxDepth || len(clause.Body) == 0 {
return step, true
}
step.Children = append(step.Children, walkStmtList(fset, src, clause.Body, depth+1, cfg, count)...)
return step, true
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L674:
if clause == nil || count == nil || *count >= cfg.MaxSteps { return walkStep{}, false }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L675:
return walkStep{}, false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L675:
- L678:
startLine := fset.Position(clause.Pos()).Line- What: Defines startLine.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L679:
var head string- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L680:
if len(clause.List) == 0 { head = "default:" } else { var parts []string for _, expr := range clause.List { parts = append(parts, strings.T…- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L681:
head = "default:"- What: Assigns head.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L683:
var parts []string- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L684:
for _, expr := range clause.List { parts = append(parts, strings.TrimSpace(nodeString(fset, expr))) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L685:
parts = append(parts, strings.TrimSpace(nodeString(fset, expr)))- What: Assigns parts.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L685:
- L687:
head = "case " + strings.Join(parts, ", ") + ":"- What: Assigns head.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L681:
- L690:
step := walkStep{ StartLine: startLine, Code: condenseSnippet(head), What: "Selects a switch case.", Why: "Makes multi-branch control flow …- What: Defines step.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L697:
*count++- What: Updates a counter.
- Why: Maintains an index or tally used by subsequent logic.
- How: Executes an increment/decrement statement.
- L698:
if *count >= cfg.MaxSteps || depth >= cfg.MaxDepth || len(clause.Body) == 0 { return step, true }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L699:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L699:
- L701:
step.Children = append(step.Children, walkStmtList(fset, src, clause.Body, depth+1, cfg, count)...)- What: Assigns step.Children.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L702:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
walkCommClause
What: Converts a select communication clause into a walkthrough step (with nested statement children).
Why: Select blocks coordinate concurrency; documenting each branch improves comprehension of control flow.
How: Builds a case <comm>: / default: header, then walks the clause body via walkStmtList.
cmd/docsgen/main.go#L705
func walkCommClause(fset *token.FileSet, src []byte, clause *ast.CommClause, depth int, cfg walkthroughConfig, count *int) (walkStep, bool) {
if clause == nil || count == nil || *count >= cfg.MaxSteps {
return walkStep{}, false
}
startLine := fset.Position(clause.Pos()).Line
head := "default:"
if clause.Comm != nil {
head = "case " + strings.TrimSpace(nodeString(fset, clause.Comm)) + ":"
}
step := walkStep{
StartLine: startLine,
Code: condenseSnippet(head),
What: "Selects a select-case branch.",
Why: "Coordinates concurrent operations without blocking incorrectly.",
How: "Runs this case body when its channel operation is ready (or runs default immediately).",
}
*count++
if *count >= cfg.MaxSteps || depth >= cfg.MaxDepth || len(clause.Body) == 0 {
return step, true
}
step.Children = append(step.Children, walkStmtList(fset, src, clause.Body, depth+1, cfg, count)...)
return step, true
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L706:
if clause == nil || count == nil || *count >= cfg.MaxSteps { return walkStep{}, false }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L707:
return walkStep{}, false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L707:
- L710:
startLine := fset.Position(clause.Pos()).Line- What: Defines startLine.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L711:
head := "default:"- What: Defines head.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L712:
if clause.Comm != nil { head = "case " + strings.TrimSpace(nodeString(fset, clause.Comm)) + ":" }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L713:
head = "case " + strings.TrimSpace(nodeString(fset, clause.Comm)) + ":"- What: Assigns head.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L713:
- L716:
step := walkStep{ StartLine: startLine, Code: condenseSnippet(head), What: "Selects a select-case branch.", Why: "Coordinates concurrent op…- What: Defines step.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L723:
*count++- What: Updates a counter.
- Why: Maintains an index or tally used by subsequent logic.
- How: Executes an increment/decrement statement.
- L724:
if *count >= cfg.MaxSteps || depth >= cfg.MaxDepth || len(clause.Body) == 0 { return step, true }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L725:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L725:
- L727:
step.Children = append(step.Children, walkStmtList(fset, src, clause.Body, depth+1, cfg, count)...)- What: Assigns step.Children.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L728:
return step, true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
funcLitsInExpr
What: Finds inline function literals (closures) within an expression tree.
Why: Core gateway code frequently embeds closures (handlers, callbacks); walkthroughs should not skip their bodies.
How: Uses ast.Inspect to collect *ast.FuncLit nodes and returns them in discovery order.
cmd/docsgen/main.go#L731
func funcLitsInExpr(expr ast.Expr) []*ast.FuncLit {
if expr == nil {
return nil
}
var lits []*ast.FuncLit
ast.Inspect(expr, func(n ast.Node) bool {
if n == nil {
return false
}
lit, ok := n.(*ast.FuncLit)
if !ok {
return true
}
lits = append(lits, lit)
return false
})
return lits
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L732:
if expr == nil { return nil }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L733:
return nil- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L733:
- L735:
var lits []*ast.FuncLit- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L736:
ast.Inspect(expr, func(n ast.Node) bool { if n == nil { return false } lit, ok := n.(*ast.FuncLit) if !ok { return true } lits = append(lit…- What: Calls ast.Inspect.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- Nested steps:
- L736:
func(n ast.Node) bool { if n == nil { return false } lit, ok := n.(*ast.FuncLit) if !ok { return true } lits = append(lits, lit) return fal…- What: Defines an inline function (closure).
- Why: Encapsulates callback logic and may capture variables from the surrounding scope.
- How: Declares a
funcliteral and uses it as a value (for example, as an HTTP handler or callback). - Nested steps:
- L737:
if n == nil { return false }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L738:
return false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L738:
- L740:
lit, ok := n.(*ast.FuncLit)- What: Defines lit, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L741:
if !ok { return true }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L742:
return true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L742:
- L744:
lits = append(lits, lit)- What: Assigns lits.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L745:
return false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L737:
- L736:
- L747:
return lits- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
describeStmt
What: Produces a generic "What/Why/How" explanation for a single Go statement node.
Why: Walkthroughs need reasonable defaults even when no human-authored commentary exists for each individual statement.
How: Uses a type switch over ast.Stmt implementations and emits short intent-focused strings (with special handling for guard if statements).
cmd/docsgen/main.go#L750
func describeStmt(fset *token.FileSet, stmt ast.Stmt) (what, why, how string) {
switch s := stmt.(type) {
case *ast.AssignStmt:
names := strings.TrimSpace(exprListString(fset, s.Lhs))
if names == "" {
names = "value(s)"
}
if s.Tok == token.DEFINE {
what = fmt.Sprintf("Defines %s.", names)
} else {
what = fmt.Sprintf("Assigns %s.", names)
}
why = "Keeps intermediate state available for later steps in the function."
how = "Evaluates the right-hand side expressions and stores results in the left-hand variables."
return what, why, how
case *ast.DeclStmt:
what = "Declares local names."
why = "Introduces variables or types used later in the function."
how = "Executes a Go declaration statement inside the function body."
return what, why, how
case *ast.IfStmt:
what = "Branches conditionally."
if isGuardIf(s) {
why = "Short-circuits early when a precondition is not met or an error/edge case is detected."
} else {
why = "Handles different execution paths based on runtime state."
}
how = "Evaluates the condition and executes the matching branch."
return what, why, how
case *ast.ReturnStmt:
what = "Returns from the current function."
why = "Ends the current execution path and hands control back to the caller."
how = "Executes a `return` statement (possibly returning values)."
return what, why, how
case *ast.ExprStmt:
if call, ok := s.X.(*ast.CallExpr); ok {
callee := strings.TrimSpace(nodeString(fset, call.Fun))
if callee != "" {
what = fmt.Sprintf("Calls %s.", callee)
} else {
what = "Calls a function."
}
} else {
what = "Evaluates an expression."
}
why = "Performs side effects or delegates work to a helper."
how = "Executes the expression statement."
return what, why, how
case *ast.ForStmt:
what = "Runs a loop."
why = "Repeats logic until a condition is met or the loop terminates."
how = "Executes a `for` loop statement."
return what, why, how
case *ast.RangeStmt:
what = "Iterates over a collection."
why = "Processes multiple elements with the same logic."
how = "Executes a `for ... range` loop."
return what, why, how
case *ast.SwitchStmt:
what = "Selects a branch from multiple cases."
why = "Keeps multi-case branching readable and explicit."
how = "Evaluates the switch expression and executes the first matching case."
return what, why, how
case *ast.TypeSwitchStmt:
what = "Selects a branch based on dynamic type."
why = "Handles multiple concrete types cleanly."
how = "Executes a type switch statement."
return what, why, how
case *ast.SelectStmt:
what = "Selects among concurrent operations."
why = "Coordinates channel operations without blocking incorrectly."
how = "Executes a `select` statement and runs one ready case."
return what, why, how
case *ast.SendStmt:
what = "Sends a value on a channel."
why = "Communicates with another goroutine."
how = "Executes a channel send operation."
return what, why, how
case *ast.DeferStmt:
what = "Defers a call for cleanup."
why = "Ensures the deferred action runs even on early returns."
how = "Schedules the call to run when the surrounding function returns."
return what, why, how
case *ast.GoStmt:
what = "Starts a goroutine."
why = "Runs work concurrently."
how = "Invokes the function call asynchronously using `go`."
return what, why, how
case *ast.IncDecStmt:
what = "Updates a counter."
why = "Maintains an index or tally used by subsequent logic."
how = "Executes an increment/decrement statement."
return what, why, how
default:
what = "Executes a statement."
why = "Advances the function logic."
how = "Runs this statement as part of the function body."
return what, why, how
}
}
Walkthrough
Expand walkthrough (90 steps)
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L751:
switch s := stmt.(type) { case *ast.AssignStmt: names := strings.TrimSpace(exprListString(fset, s.Lhs)) if names == "" { names = "value(s)"…- What: Selects a branch based on dynamic type.
- Why: Handles multiple concrete types cleanly.
- How: Executes a type switch statement.
- Nested steps:
- L751:
s := stmt.(type)- What: Defines s.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L752:
case *ast.AssignStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L753:
names := strings.TrimSpace(exprListString(fset, s.Lhs))- What: Defines names.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L754:
if names == "" { names = "value(s)" }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L755:
names = "value(s)"- What: Assigns names.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L755:
- L757:
if s.Tok == token.DEFINE { what = fmt.Sprintf("Defines %s.", names) } else { what = fmt.Sprintf("Assigns %s.", names) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L758:
what = fmt.Sprintf("Defines %s.", names)- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L760:
what = fmt.Sprintf("Assigns %s.", names)- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L758:
- L762:
why = "Keeps intermediate state available for later steps in the function."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L763:
how = "Evaluates the right-hand side expressions and stores results in the left-hand variables."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L764:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L753:
- L766:
case *ast.DeclStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L767:
what = "Declares local names."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L768:
why = "Introduces variables or types used later in the function."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L769:
how = "Executes a Go declaration statement inside the function body."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L770:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L767:
- L772:
case *ast.IfStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L773:
what = "Branches conditionally."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L774:
if isGuardIf(s) { why = "Short-circuits early when a precondition is not met or an error/edge case is detected." } else { why = "Handles di…- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L775:
why = "Short-circuits early when a precondition is not met or an error/edge case is detected."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L777:
why = "Handles different execution paths based on runtime state."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L775:
- L779:
how = "Evaluates the condition and executes the matching branch."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L780:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L773:
- L782:
case *ast.ReturnStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L783:
what = "Returns from the current function."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L784:
why = "Ends the current execution path and hands control back to the caller."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L785:
how = "Executes a `return` statement (possibly returning values)."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L786:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L783:
- L788:
case *ast.ExprStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L789:
if call, ok := s.X.(*ast.CallExpr); ok { callee := strings.TrimSpace(nodeString(fset, call.Fun)) if callee != "" { what = fmt.Sprintf("Call…- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L789:
call, ok := s.X.(*ast.CallExpr)- What: Defines call, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L790:
callee := strings.TrimSpace(nodeString(fset, call.Fun))- What: Defines callee.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L791:
if callee != "" { what = fmt.Sprintf("Calls %s.", callee) } else { what = "Calls a function." }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L792:
what = fmt.Sprintf("Calls %s.", callee)- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L794:
what = "Calls a function."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L792:
- L797:
what = "Evaluates an expression."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L789:
- L799:
why = "Performs side effects or delegates work to a helper."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L800:
how = "Executes the expression statement."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L801:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L789:
- L803:
case *ast.ForStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L804:
what = "Runs a loop."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L805:
why = "Repeats logic until a condition is met or the loop terminates."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L806:
how = "Executes a `for` loop statement."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L807:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L804:
- L809:
case *ast.RangeStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L810:
what = "Iterates over a collection."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L811:
why = "Processes multiple elements with the same logic."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L812:
how = "Executes a `for ... range` loop."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L813:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L810:
- L815:
case *ast.SwitchStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L816:
what = "Selects a branch from multiple cases."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L817:
why = "Keeps multi-case branching readable and explicit."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L818:
how = "Evaluates the switch expression and executes the first matching case."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L819:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L816:
- L821:
case *ast.TypeSwitchStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L822:
what = "Selects a branch based on dynamic type."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L823:
why = "Handles multiple concrete types cleanly."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L824:
how = "Executes a type switch statement."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L825:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L822:
- L827:
case *ast.SelectStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L828:
what = "Selects among concurrent operations."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L829:
why = "Coordinates channel operations without blocking incorrectly."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L830:
how = "Executes a `select` statement and runs one ready case."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L831:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L828:
- L833:
case *ast.SendStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L834:
what = "Sends a value on a channel."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L835:
why = "Communicates with another goroutine."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L836:
how = "Executes a channel send operation."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L837:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L834:
- L839:
case *ast.DeferStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L840:
what = "Defers a call for cleanup."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L841:
why = "Ensures the deferred action runs even on early returns."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L842:
how = "Schedules the call to run when the surrounding function returns."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L843:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L840:
- L845:
case *ast.GoStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L846:
what = "Starts a goroutine."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L847:
why = "Runs work concurrently."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L848:
how = "Invokes the function call asynchronously using `go`."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L849:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L846:
- L851:
case *ast.IncDecStmt:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L852:
what = "Updates a counter."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L853:
why = "Maintains an index or tally used by subsequent logic."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L854:
how = "Executes an increment/decrement statement."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L855:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L852:
- L857:
default:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L858:
what = "Executes a statement."- What: Assigns what.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L859:
why = "Advances the function logic."- What: Assigns why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L860:
how = "Runs this statement as part of the function body."- What: Assigns how.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L861:
return what, why, how- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L858:
- L751:
isGuardIf
What: Detects whether an if statement is an early-return guard clause.
Why: Walkthrough prose is clearer when guard clauses are labeled as "short-circuit on error/precondition failure".
How: Treats an if with no else and a body containing a return as a guard.
cmd/docsgen/main.go#L865
func isGuardIf(stmt *ast.IfStmt) bool {
if stmt == nil || stmt.Else != nil || stmt.Body == nil || len(stmt.Body.List) == 0 {
return false
}
for _, s := range stmt.Body.List {
if _, ok := s.(*ast.ReturnStmt); ok {
return true
}
}
return false
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L866:
if stmt == nil || stmt.Else != nil || stmt.Body == nil || len(stmt.Body.List) == 0 { return false }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L867:
return false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L867:
- L869:
for _, s := range stmt.Body.List { if _, ok := s.(*ast.ReturnStmt); ok { return true } }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L870:
if _, ok := s.(*ast.ReturnStmt); ok { return true }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L870:
_, ok := s.(*ast.ReturnStmt)- What: Defines _, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L871:
return true- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L870:
- L870:
- L874:
return false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
ensureAnnotationFile
What: Creates or updates an annotation YAML file with stubs for all extracted symbol IDs.
Why: When source changes, the docs need a stable place for humans to add explanations without manually discovering new symbol names.
How: Loads the existing YAML (if present), backfills missing file/title, inserts missing symbols keys, and rewrites the YAML deterministically.
cmd/docsgen/main.go#L877
func ensureAnnotationFile(path string, relSrcPath string, blocks []declBlock, funcs []funcEntry) error {
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
return err
}
anns, err := loadAnnotations(path)
if err != nil {
return err
}
if strings.TrimSpace(anns.File) == "" {
anns.File = relSrcPath
}
if strings.TrimSpace(anns.Title) == "" {
anns.Title = relSrcPath
}
if anns.Symbols == nil {
anns.Symbols = map[string]annotationText{}
}
var ids []string
for _, block := range blocks {
for _, sym := range block.Symbols {
ids = append(ids, sym.ID)
}
}
for _, fn := range funcs {
ids = append(ids, fn.ID)
}
sort.Strings(ids)
for _, id := range ids {
if _, ok := anns.Symbols[id]; !ok {
anns.Symbols[id] = annotationText{}
}
}
out, err := marshalAnnotations(anns)
if err != nil {
return err
}
return os.WriteFile(path, out, 0o644)
}
Walkthrough
Expand walkthrough (27 steps)
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L878:
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { return err }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L878:
err := os.MkdirAll(filepath.Dir(path), 0o755)- What: Defines err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L879:
return err- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L878:
- L882:
anns, err := loadAnnotations(path)- What: Defines anns, err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L883:
if err != nil { return err }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L884:
return err- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L884:
- L887:
if strings.TrimSpace(anns.File) == "" { anns.File = relSrcPath }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L888:
anns.File = relSrcPath- What: Assigns anns.File.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L888:
- L890:
if strings.TrimSpace(anns.Title) == "" { anns.Title = relSrcPath }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L891:
anns.Title = relSrcPath- What: Assigns anns.Title.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L891:
- L893:
if anns.Symbols == nil { anns.Symbols = map[string]annotationText{} }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L894:
anns.Symbols = map[string]annotationText{}- What: Assigns anns.Symbols.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L894:
- L897:
var ids []string- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L898:
for _, block := range blocks { for _, sym := range block.Symbols { ids = append(ids, sym.ID) } }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L899:
for _, sym := range block.Symbols { ids = append(ids, sym.ID) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L900:
ids = append(ids, sym.ID)- What: Assigns ids.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L900:
- L899:
- L903:
for _, fn := range funcs { ids = append(ids, fn.ID) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L904:
ids = append(ids, fn.ID)- What: Assigns ids.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L904:
- L906:
sort.Strings(ids)- What: Calls sort.Strings.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L908:
for _, id := range ids { if _, ok := anns.Symbols[id]; !ok { anns.Symbols[id] = annotationText{} } }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L909:
if _, ok := anns.Symbols[id]; !ok { anns.Symbols[id] = annotationText{} }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L909:
_, ok := anns.Symbols[id]- What: Defines _, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L910:
anns.Symbols[id] = annotationText{}- What: Assigns anns.Symbols[id].
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L909:
- L909:
- L914:
out, err := marshalAnnotations(anns)- What: Defines out, err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L915:
if err != nil { return err }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L916:
return err- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L916:
- L918:
return os.WriteFile(path, out, 0o644)- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
marshalAnnotations
What: Serializes fileAnnotations to YAML with deterministic ordering and formatting.
Why: Deterministic output reduces noisy diffs and makes it safe to auto-refresh stubs in commits.
How: Builds a yaml.Node tree, sorts symbol keys, encodes with indentation, and returns the resulting bytes.
cmd/docsgen/main.go#L921
func marshalAnnotations(anns fileAnnotations) ([]byte, error) {
root := &yaml.Node{Kind: yaml.MappingNode}
appendKV(root, "file", yamlStringNode(anns.File))
appendKV(root, "title", yamlStringNode(anns.Title))
overview := &yaml.Node{Kind: yaml.MappingNode}
appendKV(overview, "what", yamlStringNode(anns.Overview.What))
appendKV(overview, "why", yamlStringNode(anns.Overview.Why))
appendKV(overview, "how", yamlStringNode(anns.Overview.How))
appendKV(overview, "notes", yamlStringNode(anns.Overview.Notes))
appendKV(root, "overview", overview)
symbols := &yaml.Node{Kind: yaml.MappingNode}
keys := make([]string, 0, len(anns.Symbols))
for key := range anns.Symbols {
keys = append(keys, key)
}
sort.Strings(keys)
for _, key := range keys {
val := anns.Symbols[key]
entry := &yaml.Node{Kind: yaml.MappingNode}
appendKV(entry, "what", yamlStringNode(val.What))
appendKV(entry, "why", yamlStringNode(val.Why))
appendKV(entry, "how", yamlStringNode(val.How))
appendKV(entry, "notes", yamlStringNode(val.Notes))
appendKV(symbols, key, entry)
}
appendKV(root, "symbols", symbols)
var buf bytes.Buffer
enc := yaml.NewEncoder(&buf)
enc.SetIndent(2)
if err := enc.Encode(root); err != nil {
return nil, err
}
if err := enc.Close(); err != nil {
return nil, err
}
return buf.Bytes(), nil
}
Walkthrough
Expand walkthrough (33 steps)
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L922:
root := &yaml.Node{Kind: yaml.MappingNode}- What: Defines root.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L924:
appendKV(root, "file", yamlStringNode(anns.File))- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L925:
appendKV(root, "title", yamlStringNode(anns.Title))- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L927:
overview := &yaml.Node{Kind: yaml.MappingNode}- What: Defines overview.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L928:
appendKV(overview, "what", yamlStringNode(anns.Overview.What))- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L929:
appendKV(overview, "why", yamlStringNode(anns.Overview.Why))- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L930:
appendKV(overview, "how", yamlStringNode(anns.Overview.How))- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L931:
appendKV(overview, "notes", yamlStringNode(anns.Overview.Notes))- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L932:
appendKV(root, "overview", overview)- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L934:
symbols := &yaml.Node{Kind: yaml.MappingNode}- What: Defines symbols.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L935:
keys := make([]string, 0, len(anns.Symbols))- What: Defines keys.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L936:
for key := range anns.Symbols { keys = append(keys, key) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L937:
keys = append(keys, key)- What: Assigns keys.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L937:
- L939:
sort.Strings(keys)- What: Calls sort.Strings.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L940:
for _, key := range keys { val := anns.Symbols[key] entry := &yaml.Node{Kind: yaml.MappingNode} appendKV(entry, "what", yamlStringNode(val.…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L941:
val := anns.Symbols[key]- What: Defines val.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L942:
entry := &yaml.Node{Kind: yaml.MappingNode}- What: Defines entry.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L943:
appendKV(entry, "what", yamlStringNode(val.What))- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L944:
appendKV(entry, "why", yamlStringNode(val.Why))- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L945:
appendKV(entry, "how", yamlStringNode(val.How))- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L946:
appendKV(entry, "notes", yamlStringNode(val.Notes))- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L947:
appendKV(symbols, key, entry)- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L941:
- L949:
appendKV(root, "symbols", symbols)- What: Calls appendKV.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L951:
var buf bytes.Buffer- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L952:
enc := yaml.NewEncoder(&buf)- What: Defines enc.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L953:
enc.SetIndent(2)- What: Calls enc.SetIndent.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L954:
if err := enc.Encode(root); err != nil { return nil, err }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L954:
err := enc.Encode(root)- What: Defines err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L955:
return nil, err- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L954:
- L957:
if err := enc.Close(); err != nil { return nil, err }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L957:
err := enc.Close()- What: Defines err.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L958:
return nil, err- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L957:
- L960:
return buf.Bytes(), nil- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
appendKV
What: Appends a key/value pair to a YAML mapping node.
Why: The generator writes YAML stubs with stable key ordering and formatting without relying on struct tag marshaling behavior.
How: Extends node.Content with two scalar nodes: the key and the value node.
cmd/docsgen/main.go#L963
func appendKV(node *yaml.Node, key string, value *yaml.Node) {
node.Content = append(node.Content, &yaml.Node{
Kind: yaml.ScalarNode,
Tag: "!!str",
Value: key,
}, value)
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L964:
node.Content = append(node.Content, &yaml.Node{ Kind: yaml.ScalarNode, Tag: "!!str", Value: key, }, value)- What: Assigns node.Content.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
yamlStringNode
What: Builds a YAML scalar node for a string value, choosing literal style for multiline text.
Why: Multiline annotations should remain readable in YAML and should round-trip without awkward escaping.
How: Trims whitespace and sets yaml.LiteralStyle when the value contains newlines.
cmd/docsgen/main.go#L971
func yamlStringNode(value string) *yaml.Node {
value = strings.TrimSpace(value)
node := &yaml.Node{
Kind: yaml.ScalarNode,
Tag: "!!str",
Value: value,
}
if strings.Contains(value, "\n") {
node.Style = yaml.LiteralStyle
}
return node
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L972:
value = strings.TrimSpace(value)- What: Assigns value.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L973:
node := &yaml.Node{ Kind: yaml.ScalarNode, Tag: "!!str", Value: value, }- What: Defines node.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L978:
if strings.Contains(value, "\n") { node.Style = yaml.LiteralStyle }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L979:
node.Style = yaml.LiteralStyle- What: Assigns node.Style.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L979:
- L981:
return node- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
receiverTypeString
What: Formats a method receiver type as Go source text.
Why: Method symbol IDs should remain stable and human-recognizable (for example, method (*Server).ServeHTTP).
How: Prints the receiver type AST node via go/printer and trims whitespace.
cmd/docsgen/main.go#L984
func receiverTypeString(fset *token.FileSet, expr ast.Expr) string {
var buf bytes.Buffer
_ = printer.Fprint(&buf, fset, expr)
return strings.TrimSpace(buf.String())
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L985:
var buf bytes.Buffer- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L986:
_ = printer.Fprint(&buf, fset, expr)- What: Assigns _.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L987:
return strings.TrimSpace(buf.String())- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
nodeString
What: Renders an AST node (expression/statement) to a compact Go code string.
Why: Walkthrough headings and certain heuristic descriptions need readable fragments without hand-assembling them.
How: Uses go/printer.Fprint against a shared token.FileSet, then trims whitespace.
cmd/docsgen/main.go#L990
func nodeString(fset *token.FileSet, node any) string {
var buf bytes.Buffer
_ = printer.Fprint(&buf, fset, node)
return strings.TrimSpace(buf.String())
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L991:
var buf bytes.Buffer- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L992:
_ = printer.Fprint(&buf, fset, node)- What: Assigns _.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L993:
return strings.TrimSpace(buf.String())- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
exprListString
What: Formats a list of expressions into a readable string.
Why: Used to generate better inline descriptions (for example, "Defines x, y") and switch/case headings.
How: Prints each expression with go/printer and joins the results with commas.
cmd/docsgen/main.go#L996
func exprListString(fset *token.FileSet, exprs []ast.Expr) string {
if len(exprs) == 0 {
return ""
}
var parts []string
for _, expr := range exprs {
parts = append(parts, strings.TrimSpace(nodeString(fset, expr)))
}
return strings.Join(parts, ", ")
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L997:
if len(exprs) == 0 { return "" }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L998:
return ""- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L998:
- L1000:
var parts []string- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L1001:
for _, expr := range exprs { parts = append(parts, strings.TrimSpace(nodeString(fset, expr))) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1002:
parts = append(parts, strings.TrimSpace(nodeString(fset, expr)))- What: Assigns parts.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1002:
- L1004:
return strings.Join(parts, ", ")- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
sliceSource
What: Extracts the exact source substring for a token position span.
Why: Using the original bytes preserves formatting and comments in the displayed snippet (instead of pretty-printing the AST).
How: Converts token.Pos to byte offsets using the token.FileSet, validates bounds, and returns a trimmed substring.
cmd/docsgen/main.go#L1007
func sliceSource(fset *token.FileSet, src []byte, start, end token.Pos) string {
file := fset.File(start)
if file == nil {
return ""
}
startOff := file.Offset(start)
endOff := file.Offset(end)
if startOff < 0 || endOff < 0 || startOff >= len(src) || endOff > len(src) || startOff >= endOff {
return ""
}
return strings.TrimRight(string(src[startOff:endOff]), "\n")
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1008:
file := fset.File(start)- What: Defines file.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1009:
if file == nil { return "" }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1010:
return ""- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1010:
- L1012:
startOff := file.Offset(start)- What: Defines startOff.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1013:
endOff := file.Offset(end)- What: Defines endOff.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1014:
if startOff < 0 || endOff < 0 || startOff >= len(src) || endOff > len(src) || startOff >= endOff { return "" }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1015:
return ""- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1015:
- L1017:
return strings.TrimRight(string(src[startOff:endOff]), "\n")- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
condenseSnippet
What: Produces a short, single-line summary of a code fragment.
Why: Walkthrough steps render code inline; long multi-line statements would make the MDX unreadable.
How: Normalizes whitespace/newlines into a single line and truncates by rune count.
cmd/docsgen/main.go#L1020
func condenseSnippet(src string) string {
out := strings.TrimSpace(src)
if out == "" {
return out
}
out = strings.ReplaceAll(out, "\r\n", "\n")
out = strings.ReplaceAll(out, "\n", " ")
out = strings.Join(strings.Fields(out), " ")
return truncateRunes(out, 140)
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1021:
out := strings.TrimSpace(src)- What: Defines out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1022:
if out == "" { return out }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1023:
return out- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1023:
- L1025:
out = strings.ReplaceAll(out, "\r\n", "\n")- What: Assigns out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1026:
out = strings.ReplaceAll(out, "\n", " ")- What: Assigns out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1027:
out = strings.Join(strings.Fields(out), " ")- What: Assigns out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1028:
return truncateRunes(out, 140)- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
truncateRunes
What: Truncates a string to a maximum rune length, adding an ellipsis when needed.
Why: Walkthrough code previews need a predictable size regardless of Unicode input.
How: Converts to []rune for safe truncation and appends … when the string exceeds the limit.
cmd/docsgen/main.go#L1031
func truncateRunes(s string, max int) string {
if max <= 0 {
return ""
}
if len(s) <= max {
return s
}
r := []rune(s)
if len(r) <= max {
return s
}
if max <= 1 {
return string(r[:max])
}
return string(r[:max-1]) + "…"
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1032:
if max <= 0 { return "" }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1033:
return ""- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1033:
- L1035:
if len(s) <= max { return s }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1036:
return s- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1036:
- L1038:
r := []rune(s)- What: Defines r.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1039:
if len(r) <= max { return s }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1040:
return s- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1040:
- L1042:
if max <= 1 { return string(r[:max]) }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1043:
return string(r[:max])- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1043:
- L1045:
return string(r[:max-1]) + "…"- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
markdownInlineCode
What: Wraps arbitrary text as safe markdown inline code, even if it contains backticks.
Why: Walkthrough bullet items include code previews; unescaped backticks would break markdown rendering.
How: Finds the longest run of backticks in the source and chooses a delimiter one longer (adding spaces when needed).
cmd/docsgen/main.go#L1048
func markdownInlineCode(src string) string {
if strings.TrimSpace(src) == "" {
return "`(empty)`"
}
maxRun := 0
curRun := 0
for _, r := range src {
if r == '`' {
curRun++
if curRun > maxRun {
maxRun = curRun
}
} else {
curRun = 0
}
}
delim := strings.Repeat("`", maxRun+1)
if maxRun == 0 {
return "`" + src + "`"
}
return delim + " " + src + " " + delim
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1049:
if strings.TrimSpace(src) == "" { return "`(empty)`" }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1050:
return "`(empty)`"- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1050:
- L1052:
maxRun := 0- What: Defines maxRun.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1053:
curRun := 0- What: Defines curRun.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1054:
for _, r := range src { if r == '`' { curRun++ if curRun > maxRun { maxRun = curRun } } else { curRun = 0 } }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1055:
if r == '`' { curRun++ if curRun > maxRun { maxRun = curRun } } else { curRun = 0 }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1056:
curRun++- What: Updates a counter.
- Why: Maintains an index or tally used by subsequent logic.
- How: Executes an increment/decrement statement.
- L1057:
if curRun > maxRun { maxRun = curRun }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1058:
maxRun = curRun- What: Assigns maxRun.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1058:
- L1061:
curRun = 0- What: Assigns curRun.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1056:
- L1055:
- L1064:
delim := strings.Repeat("`", maxRun+1)- What: Defines delim.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1065:
if maxRun == 0 { return "`" + src + "`" }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1066:
return "`" + src + "`"- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1066:
- L1068:
return delim + " " + src + " " + delim- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
relatedSectionsForDoc
What: Declare func relatedSectionsForDoc.
Why: Centralizes behavior and avoids duplication in call sites.
How: See the Go snippet and the source link for behavior and usage.
cmd/docsgen/main.go#L1071
func relatedSectionsForDoc(doc fileDoc) []relatedSection {
src := filepath.ToSlash(doc.SrcPath)
add := func(title string, links []relatedLink) relatedSection {
out := make([]relatedLink, 0, len(links))
seen := map[string]bool{}
for _, l := range links {
if strings.TrimSpace(l.DocID) == "" || strings.TrimSpace(l.Label) == "" {
continue
}
key := l.DocID + "\n" + l.Label
if seen[key] {
continue
}
seen[key] = true
out = append(out, l)
}
return relatedSection{Title: title, Links: out}
}
var sections []relatedSection
// Shared “core navigation” links for most gateway code.
coreStartHere := []relatedLink{
{Label: "Repo tour", DocID: "start-here/repo-tour"},
{Label: "Request lifecycle", DocID: "start-here/request-lifecycle"},
}
coreArch := []relatedLink{
{Label: "Component map", DocID: "architecture/component-map"},
{Label: "Configuration model", DocID: "architecture/config"},
{Label: "Runtime composition", DocID: "architecture/runtime"},
{Label: "HTTP server", DocID: "architecture/server"},
{Label: "Proxy", DocID: "architecture/proxy"},
{Label: "Observability", DocID: "architecture/observability"},
}
switch src {
case "cmd/apigw/main.go":
sections = append(sections,
add("Start Here", append([]relatedLink{
{Label: "Local development", DocID: "start-here/local-dev"},
}, coreStartHere...)),
add("Guides", []relatedLink{
{Label: "Run the gateway", DocID: "guides/running"},
{Label: "Configure upstreams", DocID: "guides/configuration"},
{Label: "Auth and CORS", DocID: "guides/auth-cors"},
{Label: "Troubleshooting", DocID: "guides/troubleshooting"},
{Label: "Smoke script", DocID: "guides/smoke"},
}),
add("Reference", []relatedLink{
{Label: "Config reference", DocID: "reference/config"},
{Label: "Environment variables", DocID: "reference/env"},
{Label: "Admin API", DocID: "reference/admin-api"},
}),
add("Neighboring source", []relatedLink{
{Label: "Runtime", DocID: docIDForSrc("pkg/gateway/runtime/runtime.go")},
{Label: "Config", DocID: docIDForSrc("pkg/gateway/config/config.go")},
{Label: "Daemon", DocID: docIDForSrc("pkg/gateway/daemon/daemon.go")},
}),
)
case "cmd/docsgen/main.go":
sections = append(sections,
add("Docs system", []relatedLink{
{Label: "Docs tooling", DocID: "guides/documentation"},
{Label: "Annotated source index", DocID: "annotated/"},
}),
)
case "cmd/gateway/main.go":
sections = append(sections,
add("Start Here", append([]relatedLink{{Label: "Local development", DocID: "start-here/local-dev"}}, coreStartHere...)),
add("Guides", []relatedLink{
{Label: "Run the gateway", DocID: "guides/running"},
{Label: "Configure upstreams", DocID: "guides/configuration"},
}),
add("Neighboring source", []relatedLink{
{Label: "CLI (apigw)", DocID: docIDForSrc("cmd/apigw/main.go")},
{Label: "Runtime", DocID: docIDForSrc("pkg/gateway/runtime/runtime.go")},
}),
)
case "cmd/openapi/main.go", "internal/openapi/service.go":
sections = append(sections,
add("Guides", []relatedLink{{Label: "OpenAPI", DocID: "guides/openapi"}}),
add("Neighboring source", []relatedLink{
{Label: "OpenAPI merge service", DocID: docIDForSrc("internal/openapi/service.go")},
{Label: "Gateway server", DocID: docIDForSrc("pkg/gateway/server/server.go")},
}),
)
case "cmd/shadowdiff/main.go", "internal/shadowdiff/config.go", "internal/shadowdiff/diff.go", "internal/shadowdiff/fixture.go", "internal/shadowdiff/normalize.go":
sections = append(sections,
add("Guides", []relatedLink{
{Label: "Shadowdiff", DocID: "guides/shadowdiff"},
{Label: "Shadowdiff runner script", DocID: "guides/shadowdiff-runner"},
{Label: "Shadowdiff mock upstreams", DocID: "guides/shadowdiff-mocks"},
}),
add("Neighboring source", []relatedLink{
{Label: "Shadowdiff CLI", DocID: docIDForSrc("cmd/shadowdiff/main.go")},
}),
)
case "pkg/gateway/config/config.go":
sections = append(sections,
add("Start Here", coreStartHere),
add("Architecture", []relatedLink{{Label: "Configuration model", DocID: "architecture/config"}}),
add("Guides", []relatedLink{
{Label: "Configure upstreams", DocID: "guides/configuration"},
{Label: "Auth and CORS", DocID: "guides/auth-cors"},
{Label: "Webhooks", DocID: "guides/webhooks"},
{Label: "WebSockets limits", DocID: "guides/websockets"},
}),
add("Reference", []relatedLink{
{Label: "Config reference", DocID: "reference/config"},
{Label: "Environment variables", DocID: "reference/env"},
}),
add("Neighboring source", []relatedLink{
{Label: "Runtime", DocID: docIDForSrc("pkg/gateway/runtime/runtime.go")},
{Label: "Auth", DocID: docIDForSrc("pkg/gateway/auth/authenticator.go")},
{Label: "Server middleware", DocID: docIDForSrc("pkg/gateway/server/middleware/middleware.go")},
}),
)
case "pkg/gateway/daemon/daemon.go":
sections = append(sections,
add("Start Here", append([]relatedLink{{Label: "Local development", DocID: "start-here/local-dev"}}, coreStartHere...)),
add("Guides", []relatedLink{
{Label: "Run the gateway", DocID: "guides/running"},
{Label: "Troubleshooting", DocID: "guides/troubleshooting"},
}),
add("Reference", []relatedLink{
{Label: "Admin API", DocID: "reference/admin-api"},
{Label: "Environment variables", DocID: "reference/env"},
}),
add("Neighboring source", []relatedLink{
{Label: "CLI (daemon subcommands)", DocID: docIDForSrc("cmd/apigw/main.go")},
{Label: "Runtime", DocID: docIDForSrc("pkg/gateway/runtime/runtime.go")},
}),
)
case "pkg/gateway/runtime/runtime.go":
sections = append(sections,
add("Start Here", coreStartHere),
add("Architecture", []relatedLink{{Label: "Runtime composition", DocID: "architecture/runtime"}}),
add("Guides", []relatedLink{
{Label: "Run the gateway", DocID: "guides/running"},
{Label: "Troubleshooting", DocID: "guides/troubleshooting"},
}),
add("Reference", []relatedLink{
{Label: "Admin API", DocID: "reference/admin-api"},
{Label: "Metrics", DocID: "reference/metrics"},
}),
add("Neighboring source", []relatedLink{
{Label: "Config", DocID: docIDForSrc("pkg/gateway/config/config.go")},
{Label: "Server", DocID: docIDForSrc("pkg/gateway/server/server.go")},
{Label: "Proxy", DocID: docIDForSrc("pkg/gateway/proxy/reverse_proxy.go")},
{Label: "Metrics registry", DocID: docIDForSrc("pkg/gateway/metrics/registry.go")},
}),
)
case "pkg/gateway/problem/problem.go":
sections = append(sections,
add("Reference", []relatedLink{{Label: "Problem+JSON", DocID: "reference/problems"}}),
add("Neighboring source", []relatedLink{
{Label: "Server middleware", DocID: docIDForSrc("pkg/gateway/server/middleware/middleware.go")},
{Label: "Server", DocID: docIDForSrc("pkg/gateway/server/server.go")},
}),
)
case "pkg/gateway/server/server.go", "pkg/gateway/server/middleware/middleware.go", "pkg/gateway/server/protocol_metrics.go", "pkg/gateway/server/ratelimiter.go", "pkg/gateway/server/request_metadata.go":
sections = append(sections,
add("Start Here", coreStartHere),
add("Architecture", []relatedLink{{Label: "HTTP server", DocID: "architecture/server"}}),
add("Guides", []relatedLink{
{Label: "Auth and CORS", DocID: "guides/auth-cors"},
{Label: "WebSockets limits", DocID: "guides/websockets"},
{Label: "Webhooks", DocID: "guides/webhooks"},
{Label: "Troubleshooting", DocID: "guides/troubleshooting"},
}),
add("Reference", []relatedLink{
{Label: "Metrics", DocID: "reference/metrics"},
{Label: "Problem+JSON", DocID: "reference/problems"},
}),
add("Neighboring source", []relatedLink{
{Label: "Runtime", DocID: docIDForSrc("pkg/gateway/runtime/runtime.go")},
{Label: "Proxy", DocID: docIDForSrc("pkg/gateway/proxy/reverse_proxy.go")},
{Label: "Config", DocID: docIDForSrc("pkg/gateway/config/config.go")},
}),
)
case "pkg/gateway/proxy/reverse_proxy.go", "pkg/gateway/proxy/testdata/graphql_stream_server.go", "pkg/gateway/proxy/testdata/sse_server.go":
sections = append(sections,
add("Architecture", []relatedLink{{Label: "Proxy", DocID: "architecture/proxy"}}),
add("Guides", []relatedLink{
{Label: "WebSockets limits", DocID: "guides/websockets"},
{Label: "Auth and CORS", DocID: "guides/auth-cors"},
{Label: "Troubleshooting", DocID: "guides/troubleshooting"},
}),
add("Neighboring source", []relatedLink{
{Label: "Server", DocID: docIDForSrc("pkg/gateway/server/server.go")},
{Label: "Protocol metrics", DocID: docIDForSrc("pkg/gateway/server/protocol_metrics.go")},
}),
)
case "pkg/gateway/auth/authenticator.go":
sections = append(sections,
add("Guides", []relatedLink{{Label: "Auth and CORS", DocID: "guides/auth-cors"}}),
add("Reference", []relatedLink{{Label: "Environment variables", DocID: "reference/env"}}),
add("Neighboring source", []relatedLink{
{Label: "Config", DocID: docIDForSrc("pkg/gateway/config/config.go")},
{Label: "Server middleware", DocID: docIDForSrc("pkg/gateway/server/middleware/middleware.go")},
}),
)
case "examples/basic/main.go":
sections = append(sections,
add("Start Here", []relatedLink{
{Label: "Repo tour", DocID: "start-here/repo-tour"},
{Label: "Local development", DocID: "start-here/local-dev"},
}),
add("Guides", []relatedLink{{Label: "Run the gateway", DocID: "guides/running"}}),
add("Reference", []relatedLink{{Label: "Config reference", DocID: "reference/config"}}),
add("Neighboring source", []relatedLink{
{Label: "Runtime", DocID: docIDForSrc("pkg/gateway/runtime/runtime.go")},
{Label: "Config", DocID: docIDForSrc("pkg/gateway/config/config.go")},
}),
)
case "internal/service/placeholder.go":
sections = append(sections,
add("Architecture", []relatedLink{{Label: "Runtime composition", DocID: "architecture/runtime"}}),
add("Neighboring source", []relatedLink{
{Label: "Runtime", DocID: docIDForSrc("pkg/gateway/runtime/runtime.go")},
{Label: "Server", DocID: docIDForSrc("pkg/gateway/server/server.go")},
}),
)
case "pkg/gateway/webhook/handler.go":
sections = append(sections,
add("Guides", []relatedLink{{Label: "Webhooks", DocID: "guides/webhooks"}}),
add("Reference", []relatedLink{
{Label: "Config reference", DocID: "reference/config"},
{Label: "Problem+JSON", DocID: "reference/problems"},
}),
add("Neighboring source", []relatedLink{
{Label: "Config", DocID: docIDForSrc("pkg/gateway/config/config.go")},
{Label: "Server", DocID: docIDForSrc("pkg/gateway/server/server.go")},
}),
)
case "pkg/gateway/metrics/registry.go", "pkg/log/logger.go":
sections = append(sections,
add("Architecture", []relatedLink{{Label: "Observability", DocID: "architecture/observability"}}),
add("Reference", []relatedLink{{Label: "Metrics", DocID: "reference/metrics"}}),
add("Neighboring source", []relatedLink{{Label: "Protocol metrics", DocID: docIDForSrc("pkg/gateway/server/protocol_metrics.go")}}),
)
case "internal/platform/health/health.go":
sections = append(sections,
add("Start Here", []relatedLink{
{Label: "Request lifecycle", DocID: "start-here/request-lifecycle"},
}),
add("Guides", []relatedLink{{Label: "Troubleshooting", DocID: "guides/troubleshooting"}}),
add("Neighboring source", []relatedLink{
{Label: "Server", DocID: docIDForSrc("pkg/gateway/server/server.go")},
{Label: "Runtime", DocID: docIDForSrc("pkg/gateway/runtime/runtime.go")},
}),
)
default:
// For unclassified files (examples, placeholders, etc.), still provide a core navigation path.
sections = append(sections, add("Architecture", coreArch))
}
var out []relatedSection
for _, sec := range sections {
if len(sec.Links) == 0 {
continue
}
out = append(out, sec)
}
return out
}
Walkthrough
Expand walkthrough (60 steps)
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1072:
src := filepath.ToSlash(doc.SrcPath)- What: Defines src.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1074:
add := func(title string, links []relatedLink) relatedSection { out := make([]relatedLink, 0, len(links)) seen := map[string]bool{} for _, …- What: Defines add.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- Nested steps:
- L1074:
func(title string, links []relatedLink) relatedSection { out := make([]relatedLink, 0, len(links)) seen := map[string]bool{} for _, l := ra…- What: Defines an inline function (closure).
- Why: Encapsulates callback logic and may capture variables from the surrounding scope.
- How: Declares a
funcliteral and uses it as a value (for example, as an HTTP handler or callback). - Nested steps:
- L1075:
out := make([]relatedLink, 0, len(links))- What: Defines out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1076:
seen := map[string]bool{}- What: Defines seen.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1077:
for _, l := range links { if strings.TrimSpace(l.DocID) == "" || strings.TrimSpace(l.Label) == "" { continue } key := l.DocID + "\n" + l.La…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1078:
if strings.TrimSpace(l.DocID) == "" || strings.TrimSpace(l.Label) == "" { continue }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1079:
continue- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L1079:
- L1081:
key := l.DocID + "\n" + l.Label- What: Defines key.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1082:
if seen[key] { continue }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1083:
continue- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L1083:
- L1085:
seen[key] = true- What: Assigns seen[key].
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1086:
out = append(out, l)- What: Assigns out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1078:
- L1088:
return relatedSection{Title: title, Links: out}- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1075:
- L1074:
- L1091:
var sections []relatedSection- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L1094:
coreStartHere := []relatedLink{ {Label: "Repo tour", DocID: "start-here/repo-tour"}, {Label: "Request lifecycle", DocID: "start-here/reques…- What: Defines coreStartHere.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1098:
coreArch := []relatedLink{ {Label: "Component map", DocID: "architecture/component-map"}, {Label: "Configuration model", DocID: "architectu…- What: Defines coreArch.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1107:
switch src { case "cmd/apigw/main.go": sections = append(sections, add("Start Here", append([]relatedLink{ {Label: "Local development", Doc…- What: Selects a branch from multiple cases.
- Why: Keeps multi-case branching readable and explicit.
- How: Evaluates the switch expression and executes the first matching case.
- Nested steps:
- L1108:
case "cmd/apigw/main.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1109:
sections = append(sections, add("Start Here", append([]relatedLink{ {Label: "Local development", DocID: "start-here/local-dev"}, }, coreSta…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1109:
- L1132:
case "cmd/docsgen/main.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1133:
sections = append(sections, add("Docs system", []relatedLink{ {Label: "Docs tooling", DocID: "guides/documentation"}, {Label: "Annotated so…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1133:
- L1140:
case "cmd/gateway/main.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1141:
sections = append(sections, add("Start Here", append([]relatedLink{{Label: "Local development", DocID: "start-here/local-dev"}}, coreStartH…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1141:
- L1153:
case "cmd/openapi/main.go", "internal/openapi/service.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1154:
sections = append(sections, add("Guides", []relatedLink{{Label: "OpenAPI", DocID: "guides/openapi"}}), add("Neighboring source", []relatedL…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1154:
- L1162:
case "cmd/shadowdiff/main.go", "internal/shadowdiff/config.go", "internal/shadowdiff/diff.go", "internal/shadowdiff/fixture.go", "internal/…- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1163:
sections = append(sections, add("Guides", []relatedLink{ {Label: "Shadowdiff", DocID: "guides/shadowdiff"}, {Label: "Shadowdiff runner scri…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1163:
- L1174:
case "pkg/gateway/config/config.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1175:
sections = append(sections, add("Start Here", coreStartHere), add("Architecture", []relatedLink{{Label: "Configuration model", DocID: "arch…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1175:
- L1195:
case "pkg/gateway/daemon/daemon.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1196:
sections = append(sections, add("Start Here", append([]relatedLink{{Label: "Local development", DocID: "start-here/local-dev"}}, coreStartH…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1196:
- L1212:
case "pkg/gateway/runtime/runtime.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1213:
sections = append(sections, add("Start Here", coreStartHere), add("Architecture", []relatedLink{{Label: "Runtime composition", DocID: "arch…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1213:
- L1232:
case "pkg/gateway/problem/problem.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1233:
sections = append(sections, add("Reference", []relatedLink{{Label: "Problem+JSON", DocID: "reference/problems"}}), add("Neighboring source"…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1233:
- L1241:
case "pkg/gateway/server/server.go", "pkg/gateway/server/middleware/middleware.go", "pkg/gateway/server/protocol_metrics.go", "pkg/gateway/…- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1242:
sections = append(sections, add("Start Here", coreStartHere), add("Architecture", []relatedLink{{Label: "HTTP server", DocID: "architecture…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1242:
- L1262:
case "pkg/gateway/proxy/reverse_proxy.go", "pkg/gateway/proxy/testdata/graphql_stream_server.go", "pkg/gateway/proxy/testdata/sse_server.go…- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1263:
sections = append(sections, add("Architecture", []relatedLink{{Label: "Proxy", DocID: "architecture/proxy"}}), add("Guides", []relatedLink{…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1263:
- L1276:
case "pkg/gateway/auth/authenticator.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1277:
sections = append(sections, add("Guides", []relatedLink{{Label: "Auth and CORS", DocID: "guides/auth-cors"}}), add("Reference", []relatedLi…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1277:
- L1286:
case "examples/basic/main.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1287:
sections = append(sections, add("Start Here", []relatedLink{ {Label: "Repo tour", DocID: "start-here/repo-tour"}, {Label: "Local developmen…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1287:
- L1300:
case "internal/service/placeholder.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1301:
sections = append(sections, add("Architecture", []relatedLink{{Label: "Runtime composition", DocID: "architecture/runtime"}}), add("Neighbo…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1301:
- L1309:
case "pkg/gateway/webhook/handler.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1310:
sections = append(sections, add("Guides", []relatedLink{{Label: "Webhooks", DocID: "guides/webhooks"}}), add("Reference", []relatedLink{ {L…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1310:
- L1322:
case "pkg/gateway/metrics/registry.go", "pkg/log/logger.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1323:
sections = append(sections, add("Architecture", []relatedLink{{Label: "Observability", DocID: "architecture/observability"}}), add("Referen…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1323:
- L1329:
case "internal/platform/health/health.go":- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1330:
sections = append(sections, add("Start Here", []relatedLink{ {Label: "Request lifecycle", DocID: "start-here/request-lifecycle"}, }), add("…- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1330:
- L1341:
default:- What: Selects a switch case.
- Why: Makes multi-branch control flow explicit and readable.
- How: Runs this case body when the switch value matches (or when default is selected).
- Nested steps:
- L1343:
sections = append(sections, add("Architecture", coreArch))- What: Assigns sections.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1343:
- L1108:
- L1346:
var out []relatedSection- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L1347:
for _, sec := range sections { if len(sec.Links) == 0 { continue } out = append(out, sec) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1348:
if len(sec.Links) == 0 { continue }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1349:
continue- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L1349:
- L1351:
out = append(out, sec)- What: Assigns out.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1348:
- L1353:
return out- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
render
What: Renders a fileDoc plus annotations into the final MDX document bytes.
Why: Centralizes all MDX formatting so generated pages remain consistent across files and easy to evolve.
How: Writes frontmatter, source metadata, overview, grouped declaration blocks, per-symbol commentary, then function sections with snippets and walkthroughs.
cmd/docsgen/main.go#L1356
func render(doc fileDoc, anns fileAnnotations, githubBase string) []byte {
var buf bytes.Buffer
currentDocID := docIDForSrc(doc.SrcPath)
related := relatedSectionsForDoc(doc)
fmt.Fprintf(&buf, "---\n")
fmt.Fprintf(&buf, "title: %q\n", doc.Title)
if strings.TrimSpace(doc.AnnotationPath) != "" && strings.TrimSpace(githubBase) != "" {
fmt.Fprintf(&buf, "custom_edit_url: %q\n", githubBase+doc.AnnotationPath)
}
fmt.Fprintf(&buf, "---\n\n")
fmt.Fprintf(&buf, "<!--\n")
fmt.Fprintf(&buf, "Generated by `go run ./cmd/docsgen`.\n")
fmt.Fprintf(&buf, "Do not edit this file directly.\n")
fmt.Fprintf(&buf, "Edit commentary in `%s`.\n", doc.AnnotationPath)
fmt.Fprintf(&buf, "-->\n\n")
fmt.Fprintf(&buf, "## Source {#source}\n\n")
fmt.Fprintf(&buf, "- Package: `%s`\n", doc.PackageName)
fmt.Fprintf(&buf, "- File: `%s`\n", doc.SrcPath)
fmt.Fprintf(&buf, "- GitHub: %s%s\n\n", githubBase, doc.SrcPath)
overview := doc.Overview
if strings.TrimSpace(overview.What) == "" && strings.TrimSpace(overview.How) == "" && strings.TrimSpace(overview.Why) == "" {
overview.What = "This page documents the declarations in this file."
overview.How = "Use the sections below to jump to the symbol you care about, then follow the links back to source."
overview.Why = "These docs exist to make onboarding and code review faster by explaining intent, not just mechanics."
}
fmt.Fprintf(&buf, "## Overview {#overview}\n\n")
writeWhatHowWhy(&buf, overview)
sectionOrder := []string{"Imports", "Constants", "Variables", "Types"}
blocksBySection := map[string][]declBlock{}
for _, block := range doc.Blocks {
blocksBySection[block.Label] = append(blocksBySection[block.Label], block)
}
fmt.Fprintf(&buf, "\n## Contents {#contents}\n\n")
for _, section := range sectionOrder {
if len(blocksBySection[section]) == 0 {
continue
}
fmt.Fprintf(&buf, "- [%s](#%s)\n", section, strings.ToLower(section))
}
if len(doc.Funcs) > 0 {
fmt.Fprintf(&buf, "- [Functions and Methods](#functions-and-methods)\n")
}
if len(related) > 0 {
fmt.Fprintf(&buf, "- [Related docs](#related-docs)\n")
}
fmt.Fprintf(&buf, "\n")
for _, section := range sectionOrder {
blocks := blocksBySection[section]
if len(blocks) == 0 {
continue
}
fmt.Fprintf(&buf, "\n## %s {#%s}\n\n", section, strings.ToLower(section))
for i, block := range blocks {
fmt.Fprintf(&buf, "### `%s` block %d\n\n", block.Kind, i+1)
fmt.Fprintf(&buf, "```go title=%q showLineNumbers\n%s\n```\n\n", fmt.Sprintf("%s#L%d", doc.SrcPath, block.StartLine), block.Snippet)
for _, sym := range block.Symbols {
fmt.Fprintf(&buf, "#### %s {#%s}\n\n", sym.Heading, anchorIDFromSymbolID(sym.ID))
writeWhatHowWhy(&buf, resolveSymbol(anns, sym.ID))
}
}
}
if len(doc.Funcs) > 0 {
fmt.Fprintf(&buf, "\n## Functions and Methods {#functions-and-methods}\n\n")
for _, fn := range doc.Funcs {
fmt.Fprintf(&buf, "### %s {#%s}\n\n", fn.Heading, anchorIDFromSymbolID(fn.ID))
writeWhatHowWhy(&buf, resolveSymbol(anns, fn.ID))
fmt.Fprintf(&buf, "```go title=%q showLineNumbers\n%s\n```\n\n", fmt.Sprintf("%s#L%d", doc.SrcPath, fn.StartLine), fn.Snippet)
writeWalkthrough(&buf, fn.Steps)
}
}
if len(related) > 0 {
fmt.Fprintf(&buf, "\n## Related docs {#related-docs}\n\n")
for _, sec := range related {
fmt.Fprintf(&buf, "### %s\n\n", sec.Title)
for _, l := range sec.Links {
fmt.Fprintf(&buf, "- [%s](%s)\n", l.Label, linkToDoc(currentDocID, l.DocID))
}
fmt.Fprintf(&buf, "\n")
}
}
return buf.Bytes()
}
Walkthrough
Expand walkthrough (64 steps)
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1357:
var buf bytes.Buffer- What: Declares local names.
- Why: Introduces variables or types used later in the function.
- How: Executes a Go declaration statement inside the function body.
- L1359:
currentDocID := docIDForSrc(doc.SrcPath)- What: Defines currentDocID.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1360:
related := relatedSectionsForDoc(doc)- What: Defines related.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1362:
fmt.Fprintf(&buf, "---\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1363:
fmt.Fprintf(&buf, "title: %q\n", doc.Title)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1364:
if strings.TrimSpace(doc.AnnotationPath) != "" && strings.TrimSpace(githubBase) != "" { fmt.Fprintf(&buf, "custom_edit_url: %q\n", githubBa…- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1365:
fmt.Fprintf(&buf, "custom_edit_url: %q\n", githubBase+doc.AnnotationPath)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1365:
- L1367:
fmt.Fprintf(&buf, "---\n\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1369:
fmt.Fprintf(&buf, "<!--\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1370:
fmt.Fprintf(&buf, "Generated by `go run ./cmd/docsgen`.\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1371:
fmt.Fprintf(&buf, "Do not edit this file directly.\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1372:
fmt.Fprintf(&buf, "Edit commentary in `%s`.\n", doc.AnnotationPath)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1373:
fmt.Fprintf(&buf, "-->\n\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1375:
fmt.Fprintf(&buf, "## Source {#source}\n\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1376:
fmt.Fprintf(&buf, "- Package: `%s`\n", doc.PackageName)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1377:
fmt.Fprintf(&buf, "- File: `%s`\n", doc.SrcPath)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1378:
fmt.Fprintf(&buf, "- GitHub: %s%s\n\n", githubBase, doc.SrcPath)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1380:
overview := doc.Overview- What: Defines overview.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1381:
if strings.TrimSpace(overview.What) == "" && strings.TrimSpace(overview.How) == "" && strings.TrimSpace(overview.Why) == "" { overview.What…- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1382:
overview.What = "This page documents the declarations in this file."- What: Assigns overview.What.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1383:
overview.How = "Use the sections below to jump to the symbol you care about, then follow the links back to source."- What: Assigns overview.How.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1384:
overview.Why = "These docs exist to make onboarding and code review faster by explaining intent, not just mechanics."- What: Assigns overview.Why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1382:
- L1387:
fmt.Fprintf(&buf, "## Overview {#overview}\n\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1388:
writeWhatHowWhy(&buf, overview)- What: Calls writeWhatHowWhy.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1390:
sectionOrder := []string{"Imports", "Constants", "Variables", "Types"}- What: Defines sectionOrder.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1391:
blocksBySection := map[string][]declBlock{}- What: Defines blocksBySection.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1392:
for _, block := range doc.Blocks { blocksBySection[block.Label] = append(blocksBySection[block.Label], block) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1393:
blocksBySection[block.Label] = append(blocksBySection[block.Label], block)- What: Assigns blocksBySection[block.Label].
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1393:
- L1396:
fmt.Fprintf(&buf, "\n## Contents {#contents}\n\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1397:
for _, section := range sectionOrder { if len(blocksBySection[section]) == 0 { continue } fmt.Fprintf(&buf, "- [%s](#%s)\n", section, strin…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1398:
if len(blocksBySection[section]) == 0 { continue }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1399:
continue- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L1399:
- L1401:
fmt.Fprintf(&buf, "- [%s](#%s)\n", section, strings.ToLower(section))- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1398:
- L1403:
if len(doc.Funcs) > 0 { fmt.Fprintf(&buf, "- [Functions and Methods](#functions-and-methods)\n") }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1404:
fmt.Fprintf(&buf, "- [Functions and Methods](#functions-and-methods)\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1404:
- L1406:
if len(related) > 0 { fmt.Fprintf(&buf, "- [Related docs](#related-docs)\n") }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1407:
fmt.Fprintf(&buf, "- [Related docs](#related-docs)\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1407:
- L1409:
fmt.Fprintf(&buf, "\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1411:
for _, section := range sectionOrder { blocks := blocksBySection[section] if len(blocks) == 0 { continue } fmt.Fprintf(&buf, "\n## %s {#%s}…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1412:
blocks := blocksBySection[section]- What: Defines blocks.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1413:
if len(blocks) == 0 { continue }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1414:
continue- What: Executes a statement.
- Why: Advances the function logic.
- How: Runs this statement as part of the function body.
- L1414:
- L1416:
fmt.Fprintf(&buf, "\n## %s {#%s}\n\n", section, strings.ToLower(section))- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1417:
for i, block := range blocks { fmt.Fprintf(&buf, "### `%s` block %d\n\n", block.Kind, i+1) fmt.Fprintf(&buf, "```go title=%q showLineNumber…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1418:
fmt.Fprintf(&buf, "### `%s` block %d\n\n", block.Kind, i+1)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1419:
fmt.Fprintf(&buf, "```go title=%q showLineNumbers\n%s\n```\n\n", fmt.Sprintf("%s#L%d", doc.SrcPath, block.StartLine), block.Snippet)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1421:
for _, sym := range block.Symbols { fmt.Fprintf(&buf, "#### %s {#%s}\n\n", sym.Heading, anchorIDFromSymbolID(sym.ID)) writeWhatHowWhy(&buf,…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1422:
fmt.Fprintf(&buf, "#### %s {#%s}\n\n", sym.Heading, anchorIDFromSymbolID(sym.ID))- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1423:
writeWhatHowWhy(&buf, resolveSymbol(anns, sym.ID))- What: Calls writeWhatHowWhy.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1422:
- L1418:
- L1412:
- L1428:
if len(doc.Funcs) > 0 { fmt.Fprintf(&buf, "\n## Functions and Methods {#functions-and-methods}\n\n") for _, fn := range doc.Funcs { fmt.Fpr…- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1429:
fmt.Fprintf(&buf, "\n## Functions and Methods {#functions-and-methods}\n\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1430:
for _, fn := range doc.Funcs { fmt.Fprintf(&buf, "### %s {#%s}\n\n", fn.Heading, anchorIDFromSymbolID(fn.ID)) writeWhatHowWhy(&buf, resolve…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1431:
fmt.Fprintf(&buf, "### %s {#%s}\n\n", fn.Heading, anchorIDFromSymbolID(fn.ID))- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1432:
writeWhatHowWhy(&buf, resolveSymbol(anns, fn.ID))- What: Calls writeWhatHowWhy.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1433:
fmt.Fprintf(&buf, "```go title=%q showLineNumbers\n%s\n```\n\n", fmt.Sprintf("%s#L%d", doc.SrcPath, fn.StartLine), fn.Snippet)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1434:
writeWalkthrough(&buf, fn.Steps)- What: Calls writeWalkthrough.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1431:
- L1429:
- L1438:
if len(related) > 0 { fmt.Fprintf(&buf, "\n## Related docs {#related-docs}\n\n") for _, sec := range related { fmt.Fprintf(&buf, "### %s\n\…- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1439:
fmt.Fprintf(&buf, "\n## Related docs {#related-docs}\n\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1440:
for _, sec := range related { fmt.Fprintf(&buf, "### %s\n\n", sec.Title) for _, l := range sec.Links { fmt.Fprintf(&buf, "- [%s](%s)\n", l.…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1441:
fmt.Fprintf(&buf, "### %s\n\n", sec.Title)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1442:
for _, l := range sec.Links { fmt.Fprintf(&buf, "- [%s](%s)\n", l.Label, linkToDoc(currentDocID, l.DocID)) }- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1443:
fmt.Fprintf(&buf, "- [%s](%s)\n", l.Label, linkToDoc(currentDocID, l.DocID))- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1443:
- L1445:
fmt.Fprintf(&buf, "\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1441:
- L1439:
- L1449:
return buf.Bytes()- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
writeWalkthrough
What: Writes the "Walkthrough" section for a function/method.
Why: Walkthroughs are optional; this keeps MDX output small for simple files while enabling deep dives where useful.
How: Emits a short introduction and delegates to writeWalkthroughSteps for nested bullet rendering.
cmd/docsgen/main.go#L1452
func writeWalkthrough(buf *bytes.Buffer, steps []walkStep) {
if len(steps) == 0 {
return
}
totalSteps := countWalkSteps(steps)
fmt.Fprintf(buf, "#### Walkthrough\n\n")
if totalSteps > 25 {
fmt.Fprintf(buf, "<details>\n")
fmt.Fprintf(buf, "<summary>Expand walkthrough (%d steps)</summary>\n\n", totalSteps)
fmt.Fprintf(buf, "The list below documents the statements inside the function body, including nested blocks and inline closures.\n\n")
writeWalkthroughSteps(buf, steps, 0)
fmt.Fprintf(buf, "\n</details>\n\n")
return
}
fmt.Fprintf(buf, "The list below documents the statements inside the function body, including nested blocks and inline closures.\n\n")
writeWalkthroughSteps(buf, steps, 0)
fmt.Fprintf(buf, "\n")
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1453:
if len(steps) == 0 { return }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1454:
return- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1454:
- L1457:
totalSteps := countWalkSteps(steps)- What: Defines totalSteps.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1459:
fmt.Fprintf(buf, "#### Walkthrough\n\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1460:
if totalSteps > 25 { fmt.Fprintf(buf, "<details>\n") fmt.Fprintf(buf, "<summary>Expand walkthrough (%d steps)</summary>\n\n", totalSteps) f…- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1461:
fmt.Fprintf(buf, "<details>\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1462:
fmt.Fprintf(buf, "<summary>Expand walkthrough (%d steps)</summary>\n\n", totalSteps)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1463:
fmt.Fprintf(buf, "The list below documents the statements inside the function body, including nested blocks and inline closures.\n\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1464:
writeWalkthroughSteps(buf, steps, 0)- What: Calls writeWalkthroughSteps.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1465:
fmt.Fprintf(buf, "\n</details>\n\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1466:
return- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1461:
- L1469:
fmt.Fprintf(buf, "The list below documents the statements inside the function body, including nested blocks and inline closures.\n\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1470:
writeWalkthroughSteps(buf, steps, 0)- What: Calls writeWalkthroughSteps.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1471:
fmt.Fprintf(buf, "\n")- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
writeWalkthroughSteps
What: Recursively renders walkthrough steps as nested markdown lists.
Why: Nested list formatting is finicky; centralizing it avoids inconsistencies across pages and enables future formatting changes in one place.
How: Prints each step with line number, inline-code snippet, and What/Why/How bullets; prints children under a "Nested steps" bullet.
cmd/docsgen/main.go#L1474
func writeWalkthroughSteps(buf *bytes.Buffer, steps []walkStep, depth int) {
indent := strings.Repeat(" ", depth)
for _, step := range steps {
code := strings.TrimSpace(step.Code)
if code == "" {
code = "(unavailable)"
}
fmt.Fprintf(buf, "%s- **L%d**: %s\n", indent, step.StartLine, markdownInlineCode(code))
fmt.Fprintf(buf, "%s - **What:** %s\n", indent, strings.TrimSpace(step.What))
fmt.Fprintf(buf, "%s - **Why:** %s\n", indent, strings.TrimSpace(step.Why))
fmt.Fprintf(buf, "%s - **How:** %s\n", indent, strings.TrimSpace(step.How))
if len(step.Children) > 0 {
fmt.Fprintf(buf, "%s - **Nested steps:**\n", indent)
writeWalkthroughSteps(buf, step.Children, depth+2)
}
}
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1475:
indent := strings.Repeat(" ", depth)- What: Defines indent.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1476:
for _, step := range steps { code := strings.TrimSpace(step.Code) if code == "" { code = "(unavailable)" } fmt.Fprintf(buf, "%s- **L%d**: %…- What: Iterates over a collection.
- Why: Processes multiple elements with the same logic.
- How: Executes a
for ... rangeloop. - Nested steps:
- L1477:
code := strings.TrimSpace(step.Code)- What: Defines code.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1478:
if code == "" { code = "(unavailable)" }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1479:
code = "(unavailable)"- What: Assigns code.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1479:
- L1482:
fmt.Fprintf(buf, "%s- **L%d**: %s\n", indent, step.StartLine, markdownInlineCode(code))- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1483:
fmt.Fprintf(buf, "%s - **What:** %s\n", indent, strings.TrimSpace(step.What))- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1484:
fmt.Fprintf(buf, "%s - **Why:** %s\n", indent, strings.TrimSpace(step.Why))- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1485:
fmt.Fprintf(buf, "%s - **How:** %s\n", indent, strings.TrimSpace(step.How))- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1486:
if len(step.Children) > 0 { fmt.Fprintf(buf, "%s - **Nested steps:**\n", indent) writeWalkthroughSteps(buf, step.Children, depth+2) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1487:
fmt.Fprintf(buf, "%s - **Nested steps:**\n", indent)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1488:
writeWalkthroughSteps(buf, step.Children, depth+2)- What: Calls writeWalkthroughSteps.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1487:
- L1477:
resolveSymbol
What: Retrieves the human-authored annotation for a symbol ID, applying sensible defaults.
Why: Prevents pages from rendering empty sections when a symbol is new or commentary is incomplete.
How: Looks up anns.Symbols[id] and backfills missing what/why/how fields with generic guidance.
cmd/docsgen/main.go#L1493
func resolveSymbol(anns fileAnnotations, id string) annotationText {
if anns.Symbols == nil {
return annotationText{
What: fmt.Sprintf("Declare `%s`.", id),
How: "See the Go snippet and the source link for behavior and usage.",
Why: "Centralizes behavior and avoids duplication in call sites.",
}
}
if val, ok := anns.Symbols[id]; ok {
if strings.TrimSpace(val.What) == "" {
val.What = fmt.Sprintf("Declare `%s`.", id)
}
if strings.TrimSpace(val.How) == "" {
val.How = "See the Go snippet and the source link for behavior and usage."
}
if strings.TrimSpace(val.Why) == "" {
val.Why = "Centralizes behavior and avoids duplication in call sites."
}
return val
}
return annotationText{
What: fmt.Sprintf("Declare `%s`.", id),
How: "See the Go snippet and the source link for behavior and usage.",
Why: "Centralizes behavior and avoids duplication in call sites.",
}
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1494:
if anns.Symbols == nil { return annotationText{ What: fmt.Sprintf("Declare `%s`.", id), How: "See the Go snippet and the source link for be…- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1495:
return annotationText{ What: fmt.Sprintf("Declare `%s`.", id), How: "See the Go snippet and the source link for behavior and usage.", Why: …- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1495:
- L1501:
if val, ok := anns.Symbols[id]; ok { if strings.TrimSpace(val.What) == "" { val.What = fmt.Sprintf("Declare `%s`.", id) } if strings.TrimSp…- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1501:
val, ok := anns.Symbols[id]- What: Defines val, ok.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1502:
if strings.TrimSpace(val.What) == "" { val.What = fmt.Sprintf("Declare `%s`.", id) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1503:
val.What = fmt.Sprintf("Declare `%s`.", id)- What: Assigns val.What.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1503:
- L1505:
if strings.TrimSpace(val.How) == "" { val.How = "See the Go snippet and the source link for behavior and usage." }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1506:
val.How = "See the Go snippet and the source link for behavior and usage."- What: Assigns val.How.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1506:
- L1508:
if strings.TrimSpace(val.Why) == "" { val.Why = "Centralizes behavior and avoids duplication in call sites." }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1509:
val.Why = "Centralizes behavior and avoids duplication in call sites."- What: Assigns val.Why.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1509:
- L1511:
return val- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1501:
- L1513:
return annotationText{ What: fmt.Sprintf("Declare `%s`.", id), How: "See the Go snippet and the source link for behavior and usage.", Why: …- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
writeWhatHowWhy
What: Writes the standard "What / Why / How" (and optional Notes) block for an annotation.
Why: Keeps pages consistent and makes it easy to visually scan intent for every symbol.
How: Delegates each field to writeLabeledText and conditionally includes Notes when non-empty.
cmd/docsgen/main.go#L1520
func writeWhatHowWhy(buf *bytes.Buffer, t annotationText) {
writeLabeledText(buf, "What", t.What)
writeLabeledText(buf, "Why", t.Why)
writeLabeledText(buf, "How", t.How)
if strings.TrimSpace(t.Notes) != "" {
writeLabeledText(buf, "Notes", t.Notes)
}
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1521:
writeLabeledText(buf, "What", t.What)- What: Calls writeLabeledText.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1522:
writeLabeledText(buf, "Why", t.Why)- What: Calls writeLabeledText.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1523:
writeLabeledText(buf, "How", t.How)- What: Calls writeLabeledText.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1524:
if strings.TrimSpace(t.Notes) != "" { writeLabeledText(buf, "Notes", t.Notes) }- What: Branches conditionally.
- Why: Handles different execution paths based on runtime state.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1525:
writeLabeledText(buf, "Notes", t.Notes)- What: Calls writeLabeledText.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1525:
writeLabeledText
What: Writes a labeled markdown paragraph (or block) for a What/Why/How/Notes field.
Why: Improves MDX rendering for multi-paragraph text and lists by placing labels on their own line when needed.
How: Detects multiline/list-looking values and chooses either **Label:** value or a block form with blank lines.
cmd/docsgen/main.go#L1529
func writeLabeledText(buf *bytes.Buffer, label string, value string) {
value = strings.TrimSpace(value)
if value == "" {
fmt.Fprintf(buf, "**%s:**\n\n\n", label)
return
}
// When the value contains lists or multiple paragraphs, keep the label on its own line
// so markdown list markers can render correctly.
if strings.Contains(value, "\n") || strings.HasPrefix(value, "- ") || strings.HasPrefix(value, "* ") || looksLikeOrderedList(value) {
fmt.Fprintf(buf, "**%s:**\n\n%s\n\n", label, value)
return
}
fmt.Fprintf(buf, "**%s:** %s\n\n", label, value)
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1530:
value = strings.TrimSpace(value)- What: Assigns value.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1531:
if value == "" { fmt.Fprintf(buf, "**%s:**\n\n\n", label) return }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1532:
fmt.Fprintf(buf, "**%s:**\n\n\n", label)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1533:
return- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1532:
- L1538:
if strings.Contains(value, "\n") || strings.HasPrefix(value, "- ") || strings.HasPrefix(value, "* ") || looksLikeOrderedList(value) { fmt.F…- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1539:
fmt.Fprintf(buf, "**%s:**\n\n%s\n\n", label, value)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
- L1540:
return- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1539:
- L1542:
fmt.Fprintf(buf, "**%s:** %s\n\n", label, value)- What: Calls fmt.Fprintf.
- Why: Performs side effects or delegates work to a helper.
- How: Executes the expression statement.
looksLikeOrderedList
What: Heuristically detects whether a string begins with an ordered-list marker.
Why: Markdown ordered lists can break when rendered inline on the same line as a label.
How: Checks for a run of digits followed by . and then whitespace.
cmd/docsgen/main.go#L1545
func looksLikeOrderedList(value string) bool {
if value == "" {
return false
}
i := 0
for i < len(value) && value[i] >= '0' && value[i] <= '9' {
i++
}
if i == 0 || i >= len(value) {
return false
}
if value[i] != '.' {
return false
}
if i+1 >= len(value) {
return false
}
return value[i+1] == ' ' || value[i+1] == '\t'
}
Walkthrough
The list below documents the statements inside the function body, including nested blocks and inline closures.
- L1546:
if value == "" { return false }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1547:
return false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1547:
- L1549:
i := 0- What: Defines i.
- Why: Keeps intermediate state available for later steps in the function.
- How: Evaluates the right-hand side expressions and stores results in the left-hand variables.
- L1550:
for i < len(value) && value[i] >= '0' && value[i] <= '9' { i++ }- What: Runs a loop.
- Why: Repeats logic until a condition is met or the loop terminates.
- How: Executes a
forloop statement. - Nested steps:
- L1551:
i++- What: Updates a counter.
- Why: Maintains an index or tally used by subsequent logic.
- How: Executes an increment/decrement statement.
- L1551:
- L1553:
if i == 0 || i >= len(value) { return false }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1554:
return false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1554:
- L1556:
if value[i] != '.' { return false }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1557:
return false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1557:
- L1559:
if i+1 >= len(value) { return false }- What: Branches conditionally.
- Why: Short-circuits early when a precondition is not met or an error/edge case is detected.
- How: Evaluates the condition and executes the matching branch.
- Nested steps:
- L1560:
return false- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).
- L1560:
- L1562:
return value[i+1] == ' ' || value[i+1] == '\t'- What: Returns from the current function.
- Why: Ends the current execution path and hands control back to the caller.
- How: Executes a
returnstatement (possibly returning values).