Go Commands & Documentation — Professional Level¶

// The specification for doc comments (Go 1.19+):

// Paragraphs: blank line separates paragraphs
// Links: [text] or [text][url]
// Headings: A line starting with a capital letter and ending with no punctuation
// Code blocks: lines indented with a tab
// Lists: lines starting with - or *

// Example of full spec:
// Package example demonstrates doc comment formatting.
//
// Basic usage:
//
//  example.New()    // tab-indented = code block
//
// Features
//
// The package supports:
//   - fast operations
//   - concurrent access
//
// See [Go docs] for more information.
//
// [Go docs]: https://go.dev/doc
package example

// Each analyzer has this structure:
type Analyzer struct {
    Name     string
    Doc      string
    Flags    flag.FlagSet
    Run      func(*Pass) (interface{}, error)
    Requires []*Analyzer  // dependencies between analyzers
    ResultType reflect.Type
    FactTypes  []Fact
}

// A Pass gives the analyzer access to:
type Pass struct {
    Fset         *token.FileSet    // position information
    Files        []*ast.File       // syntax trees
    OtherFiles   []string          // non-Go files
    Pkg          *types.Package    // type information
    TypesInfo    *types.Info       // detailed type info
    ResultOf     map[*Analyzer]interface{}  // results from Requires
    Report       func(Diagnostic)  // report a problem
    // ...
}

// Simplified printf check logic:
func checkPrintf(pass *analysis.Pass, call *ast.CallExpr, fn *types.Func) {
    // Get format string argument
    formatArg := call.Args[fn.Params().At(0).Index()]

    // Only check if format is a string constant
    val, ok := pass.TypesInfo.Types[formatArg]
    if !ok || val.Value == nil {
        return // dynamic format string, can't check
    }

    format := constant.StringVal(val.Value)

    // Parse verbs and check against remaining args
    args := call.Args[1:]
    checkFormat(pass, call, format, args, fn)
}

// go.mod is parsed by cmd/go/internal/modfile
// It's a structured text file (NOT Go syntax)

// module path
module github.com/example/myapp

// minimum Go version required
go 1.21

// direct dependencies
require (
    github.com/gin-gonic/gin v1.9.1
    golang.org/x/sync v0.3.0
)

// indirect dependencies (transitive)
require (
    github.com/gin-contrib/sse v0.1.0 // indirect
)

// The godoc server serves:
// /pkg/             — list of all packages
// /pkg/fmt/         — package documentation
// /src/fmt/         — source code
// /search           — full-text search

// It uses the same go/doc package as go doc
// but renders to HTML using templates

// Source: golang.org/x/tools/cmd/godoc/
// Key files:
// - godoc.go: main server
// - vfs/: virtual file system for reading source
// - analysis/: cross-reference analysis (type info, callers, etc.)

// The JSON output of `go list -json .` represents this struct:
type Package struct {
    Dir           string   // directory containing package sources
    ImportPath    string   // import path of package in dir
    ImportComment string   // path in package comment on package statement
    Name          string   // package name
    Doc           string   // package documentation string
    Target        string   // install path
    Shlib         string   // the shared library that contains this package (only set when -linkshared)
    Goroot        bool     // is this package in the Go root?
    Standard      bool     // is this package part of the standard Go library?
    Stale         bool     // would 'go install' do anything for this package?
    Root          string   // Go root or Go path dir containing this package
    ConflictDir   string   // this directory shadows Dir in $GOPATH
    BinaryOnly    bool     // binary-only package: cannot be recompiled from sources
    ForTest       string   // package is only for use in named test
    Export        string   // file containing export data (when using -export)
    BuildID       string   // build ID of the compiled package
    Module        *Module  // info about package's module, if any (can be nil)
    Match         []string // command-line patterns matching this package
    DepOnly       bool     // package is only a dependency, not explicitly listed
    GoFiles       []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)
    CgoFiles      []string // .go source files that import "C"
    CompiledGoFiles []string // .go files presented to compiler
    IgnoredGoFiles []string // .go source files ignored due to build constraints
    IgnoredOtherFiles []string // non-.go source files ignored due to build constraints
    CFiles        []string // .c source files
    CXXFiles      []string // .cc, .cxx and .cpp source files
    MFiles        []string // .m source files
    HFiles        []string // .h, .hh, .hpp and .hxx source files
    FFiles        []string // .f source files (Fortran)
    SFiles        []string // .s source files
    SwigFiles     []string // .swig files
    SwigCXXFiles  []string // .swigcxx files
    SysoFiles     []string // .syso object files to add to archive
    TestGoFiles   []string // _test.go files in package
    XTestGoFiles  []string // _test.go files outside package
    CgoCFLAGS     []string // cgo: flags for C compiler
    CgoCPPFLAGS   []string // cgo: flags for C preprocessor
    CgoCXXFLAGS   []string // cgo: flags for C++ compiler
    CgoFFLAGS     []string // cgo: flags for Fortran compiler
    CgoLDFLAGS    []string // cgo: flags for linker
    CgoPkgConfig  []string // cgo: pkg-config names
    Imports       []string // import paths used by this package
    ImportMap     map[string]string // map from source import to ImportPath (identity entries omitted)
    Deps          []string // all (recursively) imported packages
    TestImports   []string // imports from TestGoFiles
    XTestImports  []string // imports from XTestGoFiles
    TestEmbedFiles []string // embed patterns from TestGoFiles
    XTestEmbedFiles []string // embed patterns from XTestGoFiles
}