docstrip

command
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Command docstrip prints the comment-stripped canonical form of one Go source file to stdout — the per-file primitive behind scripts/comments-only.sh (design 17 R-17-guard). Pipeline, per R-17-guard: parse the file with parser.ParseComments, remove its comments, and print the remainder with canonical go/printer settings. Two revisions of the same file whose docstrip outputs are byte-identical therefore differ only in comments — which is the machine proof the guard checks per changed file.

WHY NOT JUST `file.Comments = nil`: that literal recipe held on the go/printer of design 17's day, but this repo's pinned toolchain (go1.26) rewrote go/printer — it now prints doc comments from the AST's Doc fields even with File.Comments nil'd, and a merely nil'd comment leaves its line position behind, so an added comment line would shift blank lines in the printed output and fake a code diff. Instead docstrip blanks each comment's exact byte range (taken from the ParseComments parse, so strings and raw strings can never be touched) and drops lines that contained nothing but comment bytes, then re-parses the cleaned source: revisions that differ only by comments clean to byte-identical sources, hence identical canonical output, by construction.

This package is a tool, not a library: nothing in the module imports it; the wrapper invokes it via `go run ./scripts/internal/docstrip <file>`. Exit codes: 0 success · 1 the file could not be parsed or printed (the guard classifies this as RED, class "unparseable") · 2 usage error.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL