all: add godoc links

Change-Id: Ic9532893740b9952ca429106b3c373cc14d0383e
Reviewed-on: https://go-review.googlesource.com/c/mod/+/500875
Run-TryBot: Bryan Mills <bcmills@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Bryan Mills <bcmills@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Reviewed-by: Oleksandr Redko <oleksandr.red@gmail.com>
Auto-Submit: Bryan Mills <bcmills@google.com>

README.md

@@ -9,7 +9,8 @@ That is, it is for direct manipulation of Go modules themselves.
 It is NOT about supporting general development tools that
 need to do things like load packages in module mode.
 That use case, where modules are incidental rather than the focus,
-should remain in x/tools, specifically x/tools/go/packages.
+should remain in [x/tools](https://pkg.go.dev/golang/org/x/tools),
+specifically [x/tools/go/packages](https://pkg.go.dev/golang.org/x/tools/go/packages).
 
 The specific case of loading packages should still be done by
 invoking the go command, which remains the single point of

internal/lazyregexp/lazyre.go

@@ -13,7 +13,7 @@ import (
 	"sync"
 )
 
-// Regexp is a wrapper around regexp.Regexp, where the underlying regexp will be
+// Regexp is a wrapper around [regexp.Regexp], where the underlying regexp will be
 // compiled the first time it is needed.
 type Regexp struct {
 	str  string

modfile/read.go

@@ -65,7 +65,7 @@ type Comments struct {
 }
 
 // Comment returns the receiver. This isn't useful by itself, but
-// a Comments struct is embedded into all the expression
+// a [Comments] struct is embedded into all the expression
 // implementation types, and this gives each of those a Comment
 // method to satisfy the Expr interface.
 func (c *Comments) Comment() *Comments {

modfile/rule.go

@@ -5,17 +5,17 @@
 // Package modfile implements a parser and formatter for go.mod files.
 //
 // The go.mod syntax is described in
-// https://golang.org/cmd/go/#hdr-The_go_mod_file.
+// https://pkg.go.dev/cmd/go/#hdr-The_go_mod_file.
 //
-// The Parse and ParseLax functions both parse a go.mod file and return an
+// The [Parse] and [ParseLax] functions both parse a go.mod file and return an
 // abstract syntax tree. ParseLax ignores unknown statements and may be used to
 // parse go.mod files that may have been developed with newer versions of Go.
 //
-// The File struct returned by Parse and ParseLax represent an abstract
-// go.mod file. File has several methods like AddNewRequire and DropReplace
-// that can be used to programmatically edit a file.
+// The [File] struct returned by Parse and ParseLax represent an abstract
+// go.mod file. File has several methods like [File.AddNewRequire] and
+// [File.DropReplace] that can be used to programmatically edit a file.
 //
-// The Format function formats a File back to a byte slice which can be
+// The [Format] function formats a File back to a byte slice which can be
 // written to a file.
 package modfile
 
@@ -226,7 +226,7 @@ var dontFixRetract VersionFixer = func(_, vers string) (string, error) {
 // data is the content of the file.
 //
 // fix is an optional function that canonicalizes module versions.
-// If fix is nil, all module versions must be canonical (module.CanonicalVersion
+// If fix is nil, all module versions must be canonical ([module.CanonicalVersion]
 // must return the same string).
 func Parse(file string, data []byte, fix VersionFixer) (*File, error) {
 	return parseToFile(file, data, fix, true)
@@ -923,7 +923,7 @@ func (f *File) Format() ([]byte, error) {
 }
 
 // Cleanup cleans up the file f after any edit operations.
-// To avoid quadratic behavior, modifications like DropRequire
+// To avoid quadratic behavior, modifications like [File.DropRequire]
 // clear the entry but do not remove it from the slice.
 // Cleanup cleans out all the cleared entries.
 func (f *File) Cleanup() {
@@ -1075,8 +1075,8 @@ func (f *File) AddNewRequire(path, vers string, indirect bool) {
 // The requirements in req must specify at most one distinct version for each
 // module path.
 //
-// If any existing requirements may be removed, the caller should call Cleanup
-// after all edits are complete.
+// If any existing requirements may be removed, the caller should call
+// [File.Cleanup] after all edits are complete.
 func (f *File) SetRequire(req []*Require) {
 	type elem struct {
 		version  string

modfile/work.go

@@ -34,7 +34,7 @@ type Use struct {
 // data is the content of the file.
 //
 // fix is an optional function that canonicalizes module versions.
-// If fix is nil, all module versions must be canonical (module.CanonicalVersion
+// If fix is nil, all module versions must be canonical ([module.CanonicalVersion]
 // must return the same string).
 func ParseWork(file string, data []byte, fix VersionFixer) (*WorkFile, error) {
 	fs, err := parse(file, data)
@@ -83,7 +83,7 @@ func ParseWork(file string, data []byte, fix VersionFixer) (*WorkFile, error) {
 }
 
 // Cleanup cleans up the file f after any edit operations.
-// To avoid quadratic behavior, modifications like DropRequire
+// To avoid quadratic behavior, modifications like [WorkFile.DropRequire]
 // clear the entry but do not remove it from the slice.
 // Cleanup cleans out all the cleared entries.
 func (f *WorkFile) Cleanup() {

module/module.go

@@ -4,7 +4,7 @@
 
 // Package module defines the module.Version type along with support code.
 //
-// The module.Version type is a simple Path, Version pair:
+// The [module.Version] type is a simple Path, Version pair:
 //
 //	type Version struct {
 //		Path string
@@ -12,7 +12,7 @@
 //	}
 //
 // There are no restrictions imposed directly by use of this structure,
-// but additional checking functions, most notably Check, verify that
+// but additional checking functions, most notably [Check], verify that
 // a particular path, version pair is valid.
 //
 // # Escaped Paths
@@ -140,7 +140,7 @@ type ModuleError struct {
 	Err     error
 }
 
-// VersionError returns a ModuleError derived from a Version and error,
+// VersionError returns a [ModuleError] derived from a [Version] and error,
 // or err itself if it is already such an error.
 func VersionError(v Version, err error) error {
 	var mErr *ModuleError
@@ -169,7 +169,7 @@ func (e *ModuleError) Unwrap() error { return e.Err }
 // An InvalidVersionError indicates an error specific to a version, with the
 // module path unknown or specified externally.
 //
-// A ModuleError may wrap an InvalidVersionError, but an InvalidVersionError
+// A [ModuleError] may wrap an InvalidVersionError, but an InvalidVersionError
 // must not wrap a ModuleError.
 type InvalidVersionError struct {
 	Version string
@@ -193,8 +193,8 @@ func (e *InvalidVersionError) Error() string {
 func (e *InvalidVersionError) Unwrap() error { return e.Err }
 
 // An InvalidPathError indicates a module, import, or file path doesn't
-// satisfy all naming constraints. See CheckPath, CheckImportPath,
-// and CheckFilePath for specific restrictions.
+// satisfy all naming constraints. See [CheckPath], [CheckImportPath],
+// and [CheckFilePath] for specific restrictions.
 type InvalidPathError struct {
 	Kind string // "module", "import", or "file"
 	Path string
@@ -294,7 +294,7 @@ func fileNameOK(r rune) bool {
 }
 
 // CheckPath checks that a module path is valid.
-// A valid module path is a valid import path, as checked by CheckImportPath,
+// A valid module path is a valid import path, as checked by [CheckImportPath],
 // with three additional constraints.
 // First, the leading path element (up to the first slash, if any),
 // by convention a domain name, must contain only lower-case ASCII letters,
@@ -380,7 +380,7 @@ const (
 // checkPath returns an error describing why the path is not valid.
 // Because these checks apply to module, import, and file paths,
 // and because other checks may be applied, the caller is expected to wrap
-// this error with InvalidPathError.
+// this error with [InvalidPathError].
 func checkPath(path string, kind pathKind) error {
 	if !utf8.ValidString(path) {
 		return fmt.Errorf("invalid UTF-8")
@@ -532,7 +532,7 @@ var badWindowsNames = []string{
 // they require ".vN" instead of "/vN", and for all N, not just N >= 2.
 // SplitPathVersion returns with ok = false when presented with
 // a path whose last path element does not satisfy the constraints
-// applied by CheckPath, such as "example.com/pkg/v1" or "example.com/pkg/v1.2".
+// applied by [CheckPath], such as "example.com/pkg/v1" or "example.com/pkg/v1.2".
 func SplitPathVersion(path string) (prefix, pathMajor string, ok bool) {
 	if strings.HasPrefix(path, "gopkg.in/") {
 		return splitGopkgIn(path)
@@ -582,7 +582,7 @@ func splitGopkgIn(path string) (prefix, pathMajor string, ok bool) {
 // MatchPathMajor reports whether the semantic version v
 // matches the path major version pathMajor.
 //
-// MatchPathMajor returns true if and only if CheckPathMajor returns nil.
+// MatchPathMajor returns true if and only if [CheckPathMajor] returns nil.
 func MatchPathMajor(v, pathMajor string) bool {
 	return CheckPathMajor(v, pathMajor) == nil
 }
@@ -622,7 +622,7 @@ func CheckPathMajor(v, pathMajor string) error {
 // PathMajorPrefix returns the major-version tag prefix implied by pathMajor.
 // An empty PathMajorPrefix allows either v0 or v1.
 //
-// Note that MatchPathMajor may accept some versions that do not actually begin
+// Note that [MatchPathMajor] may accept some versions that do not actually begin
 // with this prefix: namely, it accepts a 'v0.0.0-' prefix for a '.v1'
 // pathMajor, even though that pathMajor implies 'v1' tagging.
 func PathMajorPrefix(pathMajor string) string {
@@ -643,7 +643,7 @@ func PathMajorPrefix(pathMajor string) string {
 }
 
 // CanonicalVersion returns the canonical form of the version string v.
-// It is the same as semver.Canonical(v) except that it preserves the special build suffix "+incompatible".
+// It is the same as [semver.Canonical] except that it preserves the special build suffix "+incompatible".
 func CanonicalVersion(v string) string {
 	cv := semver.Canonical(v)
 	if semver.Build(v) == "+incompatible" {
@@ -652,8 +652,8 @@ func CanonicalVersion(v string) string {
 	return cv
 }
 
-// Sort sorts the list by Path, breaking ties by comparing Version fields.
-// The Version fields are interpreted as semantic versions (using semver.Compare)
+// Sort sorts the list by Path, breaking ties by comparing [Version] fields.
+// The Version fields are interpreted as semantic versions (using [semver.Compare])
 // optionally followed by a tie-breaking suffix introduced by a slash character,
 // like in "v0.0.1/go.mod".
 func Sort(list []Version) {
@@ -793,7 +793,7 @@ func unescapeString(escaped string) (string, bool) {
 }
 
 // MatchPrefixPatterns reports whether any path prefix of target matches one of
-// the glob patterns (as defined by path.Match) in the comma-separated globs
+// the glob patterns (as defined by [path.Match]) in the comma-separated globs
 // list. This implements the algorithm used when matching a module path to the
 // GOPRIVATE environment variable, as described by 'go help module-private'.
 //

module/pseudo.go

@@ -125,7 +125,7 @@ func IsPseudoVersion(v string) bool {
 }
 
 // IsZeroPseudoVersion returns whether v is a pseudo-version with a zero base,
-// timestamp, and revision, as returned by ZeroPseudoVersion.
+// timestamp, and revision, as returned by [ZeroPseudoVersion].
 func IsZeroPseudoVersion(v string) bool {
 	return v == ZeroPseudoVersion(semver.Major(v))
 }

semver/semver.go

@@ -140,7 +140,7 @@ func Compare(v, w string) int {
 // Max canonicalizes its arguments and then returns the version string
 // that compares greater.
 //
-// Deprecated: use Compare instead. In most cases, returning a canonicalized
+// Deprecated: use [Compare] instead. In most cases, returning a canonicalized
 // version is not expected or desired.
 func Max(v, w string) string {
 	v = Canonical(v)
@@ -151,7 +151,7 @@ func Max(v, w string) string {
 	return w
 }
 
-// ByVersion implements sort.Interface for sorting semantic version strings.
+// ByVersion implements [sort.Interface] for sorting semantic version strings.
 type ByVersion []string
 
 func (vs ByVersion) Len() int      { return len(vs) }
@@ -164,7 +164,7 @@ func (vs ByVersion) Less(i, j int) bool {
 	return vs[i] < vs[j]
 }
 
-// Sort sorts a list of semantic version strings using ByVersion.
+// Sort sorts a list of semantic version strings using [ByVersion].
 func Sort(list []string) {
 	sort.Sort(ByVersion(list))
 }

sumdb/client.go

@@ -19,7 +19,7 @@ import (
 )
 
 // A ClientOps provides the external operations
-// (file caching, HTTP fetches, and so on) needed by the Client.
+// (file caching, HTTP fetches, and so on) needed by the [Client].
 // The methods must be safe for concurrent use by multiple goroutines.
 type ClientOps interface {
 	// ReadRemote reads and returns the content served at the given path
@@ -72,7 +72,7 @@ type ClientOps interface {
 // ErrWriteConflict signals a write conflict during Client.WriteConfig.
 var ErrWriteConflict = errors.New("write conflict")
 
-// ErrSecurity is returned by Client operations that invoke Client.SecurityError.
+// ErrSecurity is returned by [Client] operations that invoke Client.SecurityError.
 var ErrSecurity = errors.New("security error: misbehaving server")
 
 // A Client is a client connection to a checksum database.
@@ -102,7 +102,7 @@ type Client struct {
 	tileSaved   map[tlog.Tile]bool // which tiles have been saved using c.ops.WriteCache already
 }
 
-// NewClient returns a new Client using the given Client.
+// NewClient returns a new [Client] using the given [ClientOps].
 func NewClient(ops ClientOps) *Client {
 	return &Client{
 		ops: ops,
@@ -155,7 +155,7 @@ func (c *Client) initWork() {
 }
 
 // SetTileHeight sets the tile height for the Client.
-// Any call to SetTileHeight must happen before the first call to Lookup.
+// Any call to SetTileHeight must happen before the first call to [Client.Lookup].
 // If SetTileHeight is not called, the Client defaults to tile height 8.
 // SetTileHeight can be called at most once,
 // and if so it must be called before the first call to Lookup.
@@ -174,7 +174,7 @@ func (c *Client) SetTileHeight(height int) {
 
 // SetGONOSUMDB sets the list of comma-separated GONOSUMDB patterns for the Client.
 // For any module path matching one of the patterns,
-// Lookup will return ErrGONOSUMDB.
+// [Client.Lookup] will return ErrGONOSUMDB.
 // SetGONOSUMDB can be called at most once,
 // and if so it must be called before the first call to Lookup.
 func (c *Client) SetGONOSUMDB(list string) {
@@ -187,8 +187,8 @@ func (c *Client) SetGONOSUMDB(list string) {
 	c.nosumdb = list
 }
 
-// ErrGONOSUMDB is returned by Lookup for paths that match
-// a pattern listed in the GONOSUMDB list (set by SetGONOSUMDB,
+// ErrGONOSUMDB is returned by [Client.Lookup] for paths that match
+// a pattern listed in the GONOSUMDB list (set by [Client.SetGONOSUMDB],
 // usually from the environment variable).
 var ErrGONOSUMDB = errors.New("skipped (listed in GONOSUMDB)")
 

sumdb/note/note.go

@@ -20,45 +20,45 @@
 //
 // # Verifying Notes
 //
-// A Verifier allows verification of signatures by one server public key.
+// A [Verifier] allows verification of signatures by one server public key.
 // It can report the name of the server and the uint32 hash of the key,
 // and it can verify a purported signature by that key.
 //
 // The standard implementation of a Verifier is constructed
-// by NewVerifier starting from a verifier key, which is a
+// by [NewVerifier] starting from a verifier key, which is a
 // plain text string of the form "<name>+<hash>+<keydata>".
 //
-// A Verifiers allows looking up a Verifier by the combination
+// A [Verifiers] allows looking up a Verifier by the combination
 // of server name and key hash.
 //
 // The standard implementation of a Verifiers is constructed
 // by VerifierList from a list of known verifiers.
 //
-// A Note represents a text with one or more signatures.
+// A [Note] represents a text with one or more signatures.
 // An implementation can reject a note with too many signatures
 // (for example, more than 100 signatures).
 //
-// A Signature represents a signature on a note, verified or not.
+// A [Signature] represents a signature on a note, verified or not.
 //
-// The Open function takes as input a signed message
+// The [Open] function takes as input a signed message
 // and a set of known verifiers. It decodes and verifies
-// the message signatures and returns a Note structure
+// the message signatures and returns a [Note] structure
 // containing the message text and (verified or unverified) signatures.
 //
 // # Signing Notes
 //
-// A Signer allows signing a text with a given key.
+// A [Signer] allows signing a text with a given key.
 // It can report the name of the server and the hash of the key
 // and can sign a raw text using that key.
 //
 // The standard implementation of a Signer is constructed
-// by NewSigner starting from an encoded signer key, which is a
+// by [NewSigner] starting from an encoded signer key, which is a
 // plain text string of the form "PRIVATE+KEY+<name>+<hash>+<keydata>".
 // Anyone with an encoded signer key can sign messages using that key,
 // so it must be kept secret. The encoding begins with the literal text
 // "PRIVATE+KEY" to avoid confusion with the public server key.
 //
-// The Sign function takes as input a Note and a list of Signers
+// The [Sign] function takes as input a Note and a list of Signers
 // and returns an encoded, signed message.
 //
 // # Signed Note Format
@@ -88,7 +88,7 @@
 // although doing so will require deploying the new algorithms to all clients
 // before starting to depend on them for signatures.
 //
-// The GenerateKey function generates and returns a new signer
+// The [GenerateKey] function generates and returns a new signer
 // and corresponding verifier.
 //
 // # Example
@@ -123,9 +123,9 @@
 // base URLs, the only syntactic requirement is that they
 // not contain spaces or newlines).
 //
-// If Open is given access to a Verifiers including the
-// Verifier for this key, then it will succeed at verifying
-// the encoded message and returning the parsed Note:
+// If [Open] is given access to a [Verifiers] including the
+// [Verifier] for this key, then it will succeed at verifying
+// the encoded message and returning the parsed [Note]:
 //
 //	vkey := "PeterNeumann+c74f20a3+ARpc2QcUPDhMQegwxbzhKqiBfsVkmqq/LDE4izWy10TW"
 //	msg := []byte("If you think cryptography is the answer to your problem,\n" +
@@ -238,7 +238,7 @@ func isValidName(name string) bool {
 	return name != "" && utf8.ValidString(name) && strings.IndexFunc(name, unicode.IsSpace) < 0 && !strings.Contains(name, "+")
 }
 
-// NewVerifier construct a new Verifier from an encoded verifier key.
+// NewVerifier construct a new [Verifier] from an encoded verifier key.
 func NewVerifier(vkey string) (Verifier, error) {
 	name, vkey := chop(vkey, "+")
 	hash16, key64 := chop(vkey, "+")
@@ -295,7 +295,7 @@ func (v *verifier) Name() string                { return v.name }
 func (v *verifier) KeyHash() uint32             { return v.hash }
 func (v *verifier) Verify(msg, sig []byte) bool { return v.verify(msg, sig) }
 
-// NewSigner constructs a new Signer from an encoded signer key.
+// NewSigner constructs a new [Signer] from an encoded signer key.
 func NewSigner(skey string) (Signer, error) {
 	priv1, skey := chop(skey, "+")
 	priv2, skey := chop(skey, "+")
@@ -409,7 +409,7 @@ func (e *UnknownVerifierError) Error() string {
 }
 
 // An ambiguousVerifierError indicates that the given name and hash
-// match multiple keys passed to VerifierList.
+// match multiple keys passed to [VerifierList].
 // (If this happens, some malicious actor has taken control of the
 // verifier list, at which point we may as well give up entirely,
 // but we diagnose the problem instead.)
@@ -422,7 +422,7 @@ func (e *ambiguousVerifierError) Error() string {
 	return fmt.Sprintf("ambiguous key %s+%08x", e.name, e.hash)
 }
 
-// VerifierList returns a Verifiers implementation that uses the given list of verifiers.
+// VerifierList returns a [Verifiers] implementation that uses the given list of verifiers.
 func VerifierList(list ...Verifier) Verifiers {
 	m := make(verifierMap)
 	for _, v := range list {
@@ -510,7 +510,7 @@ var (
 // If known.Verifier returns any other error, Open returns that error.
 //
 // If no known verifier has signed an otherwise valid note,
-// Open returns an UnverifiedNoteError.
+// Open returns an [UnverifiedNoteError].
 // In this case, the unverified note can be fetched from inside the error.
 func Open(msg []byte, known Verifiers) (*Note, error) {
 	if known == nil {

sumdb/server.go

@@ -17,7 +17,7 @@ import (
 )
 
 // A ServerOps provides the external operations
-// (underlying database access and so on) needed by the Server.
+// (underlying database access and so on) needed by the [Server].
 type ServerOps interface {
 	// Signed returns the signed hash of the latest tree.
 	Signed(ctx context.Context) ([]byte, error)
@@ -36,7 +36,7 @@ type ServerOps interface {
 
 // A Server is the checksum database HTTP server,
 // which implements http.Handler and should be invoked
-// to serve the paths listed in ServerPaths.
+// to serve the paths listed in [ServerPaths].
 type Server struct {
 	ops ServerOps
 }

sumdb/storage/mem.go

@@ -11,7 +11,7 @@ import (
 	"sync"
 )
 
-// Mem is an in-memory implementation of Storage.
+// Mem is an in-memory implementation of [Storage].
 // It is meant for tests and does not store any data to persistent storage.
 //
 // The zero value is an empty Mem ready for use.

sumdb/storage/storage.go

@@ -27,7 +27,7 @@ type Storage interface {
 }
 
 // A Transaction provides read and write operations within a transaction,
-// as executed by Storage's ReadOnly or ReadWrite methods.
+// as executed by [Storage]'s ReadOnly or ReadWrite methods.
 type Transaction interface {
 	// ReadValue reads the value associated with a single key.
 	// If there is no value associated with that key, ReadKey returns an empty value.

sumdb/test.go

@@ -14,15 +14,15 @@ import (
 	"golang.org/x/mod/sumdb/tlog"
 )
 
-// NewTestServer constructs a new TestServer
+// NewTestServer constructs a new [TestServer]
 // that will sign its tree with the given signer key
-// (see golang.org/x/mod/sumdb/note)
+// (see [golang.org/x/mod/sumdb/note])
 // and fetch new records as needed by calling gosum.
 func NewTestServer(signer string, gosum func(path, vers string) ([]byte, error)) *TestServer {
 	return &TestServer{signer: signer, gosum: gosum}
 }
 
-// A TestServer is an in-memory implementation of Server for testing.
+// A TestServer is an in-memory implementation of [ServerOps] for testing.
 type TestServer struct {
 	signer string
 	gosum  func(path, vers string) ([]byte, error)

sumdb/tlog/tile.go

@@ -28,7 +28,7 @@ import (
 // is tile/3/4/x001/x234/067.p/1, and
 // Tile{H: 3, L: 4, N: 1234067, W: 8}'s path
 // is tile/3/4/x001/x234/067.
-// See Tile's Path method and the ParseTilePath function.
+// See the [Tile.Path] method and the [ParseTilePath] function.
 //
 // The special level L=-1 holds raw record data instead of hashes.
 // In this case, the level encodes into a tile path as the path element
@@ -46,7 +46,7 @@ type Tile struct {
 // TileForIndex returns the tile of fixed height h ≥ 1
 // and least width storing the given hash storage index.
 //
-// If h ≤ 0, TileForIndex panics.
+// If h ≤ 0, [TileForIndex] panics.
 func TileForIndex(h int, index int64) Tile {
 	if h <= 0 {
 		panic(fmt.Sprintf("TileForIndex: invalid height %d", h))
@@ -105,7 +105,7 @@ func tileHash(data []byte) Hash {
 // size newTreeSize to replace a tree of size oldTreeSize.
 // (No tiles need to be published for a tree of size zero.)
 //
-// If h ≤ 0, TileForIndex panics.
+// If h ≤ 0, NewTiles panics.
 func NewTiles(h int, oldTreeSize, newTreeSize int64) []Tile {
 	if h <= 0 {
 		panic(fmt.Sprintf("NewTiles: invalid height %d", h))
@@ -272,7 +272,7 @@ type TileReader interface {
 // TileHashReader returns a HashReader that satisfies requests
 // by loading tiles of the given tree.
 //
-// The returned HashReader checks that loaded tiles are
+// The returned [HashReader] checks that loaded tiles are
 // valid for the given tree. Therefore, any hashes returned
 // by the HashReader are already proven to be in the tree.
 func TileHashReader(tree Tree, tr TileReader) HashReader {

sumdb/tlog/tlog.go

@@ -131,7 +131,7 @@ func StoredHashIndex(level int, n int64) int64 {
 	return i + int64(level)
 }
 
-// SplitStoredHashIndex is the inverse of StoredHashIndex.
+// SplitStoredHashIndex is the inverse of [StoredHashIndex].
 // That is, SplitStoredHashIndex(StoredHashIndex(level, n)) == level, n.
 func SplitStoredHashIndex(index int64) (level int, n int64) {
 	// Determine level 0 record before index.
@@ -183,7 +183,7 @@ func StoredHashes(n int64, data []byte, r HashReader) ([]Hash, error) {
 	return StoredHashesForRecordHash(n, RecordHash(data), r)
 }
 
-// StoredHashesForRecordHash is like StoredHashes but takes
+// StoredHashesForRecordHash is like [StoredHashes] but takes
 // as its second argument RecordHash(data) instead of data itself.
 func StoredHashesForRecordHash(n int64, h Hash, r HashReader) ([]Hash, error) {
 	// Start with the record hash.
@@ -227,7 +227,7 @@ type HashReader interface {
 	ReadHashes(indexes []int64) ([]Hash, error)
 }
 
-// A HashReaderFunc is a function implementing HashReader.
+// A HashReaderFunc is a function implementing [HashReader].
 type HashReaderFunc func([]int64) ([]Hash, error)
 
 func (f HashReaderFunc) ReadHashes(indexes []int64) ([]Hash, error) {

zip/zip.go

@@ -10,31 +10,31 @@
 //
 // • All file paths within a zip file must start with "<module>@<version>/",
 // where "<module>" is the module path and "<version>" is the version.
-// The module path must be valid (see golang.org/x/mod/module.CheckPath).
+// The module path must be valid (see [golang.org/x/mod/module.CheckPath]).
 // The version must be valid and canonical (see
-// golang.org/x/mod/module.CanonicalVersion). The path must have a major
+// [golang.org/x/mod/module.CanonicalVersion]). The path must have a major
 // version suffix consistent with the version (see
-// golang.org/x/mod/module.Check). The part of the file path after the
+// [golang.org/x/mod/module.Check]). The part of the file path after the
 // "<module>@<version>/" prefix must be valid (see
-// golang.org/x/mod/module.CheckFilePath).
+// [golang.org/x/mod/module.CheckFilePath]).
 //
 // • No two file paths may be equal under Unicode case-folding (see
-// strings.EqualFold).
+// [strings.EqualFold]).
 //
 // • A go.mod file may or may not appear in the top-level directory. If present,
 // it must be named "go.mod", not any other case. Files named "go.mod"
 // are not allowed in any other directory.
 //
-// • The total size in bytes of a module zip file may be at most MaxZipFile
+// • The total size in bytes of a module zip file may be at most [MaxZipFile]
 // bytes (500 MiB). The total uncompressed size of the files within the
-// zip may also be at most MaxZipFile bytes.
+// zip may also be at most [MaxZipFile] bytes.
 //
 // • Each file's uncompressed size must match its declared 64-bit uncompressed
 // size in the zip file header.
 //
 // • If the zip contains files named "<module>@<version>/go.mod" or
 // "<module>@<version>/LICENSE", their sizes in bytes may be at most
-// MaxGoMod or MaxLICENSE, respectively (both are 16 MiB).
+// [MaxGoMod] or [MaxLICENSE], respectively (both are 16 MiB).
 //
 // • Empty directories are ignored. File permissions and timestamps are also
 // ignored.
@@ -42,7 +42,7 @@
 // • Symbolic links and other irregular files are not allowed.
 //
 // Note that this package does not provide hashing functionality. See
-// golang.org/x/mod/sumdb/dirhash.
+// [golang.org/x/mod/sumdb/dirhash].
 package zip
 
 import (
@@ -118,8 +118,9 @@ type CheckedFiles struct {
 	SizeError error
 }
 
-// Err returns an error if CheckedFiles does not describe a valid module zip
-// file. SizeError is returned if that field is set. A FileErrorList is returned
+// Err returns an error if [CheckedFiles] does not describe a valid module zip
+// file. [CheckedFiles.SizeError] is returned if that field is set.
+// A [FileErrorList] is returned
 // if there are one or more invalid files. Other errors may be returned in the
 // future.
 func (cf CheckedFiles) Err() error {
@@ -322,17 +323,17 @@ func checkFiles(files []File) (cf CheckedFiles, validFiles []File, validSizes []
 }
 
 // CheckDir reports whether the files in dir satisfy the name and size
-// constraints listed in the package documentation. The returned CheckedFiles
+// constraints listed in the package documentation. The returned [CheckedFiles]
 // record contains lists of valid, invalid, and omitted files. If a directory is
 // omitted (for example, a nested module or vendor directory), it will appear in
 // the omitted list, but its files won't be listed.
 //
 // CheckDir returns an error if it encounters an I/O error or if the returned
-// CheckedFiles does not describe a valid module zip file (according to
-// CheckedFiles.Err). The returned CheckedFiles is still populated when such
+// [CheckedFiles] does not describe a valid module zip file (according to
+// [CheckedFiles.Err]). The returned [CheckedFiles] is still populated when such
 // an error is returned.
 //
-// Note that CheckDir will not open any files, so CreateFromDir may still fail
+// Note that CheckDir will not open any files, so [CreateFromDir] may still fail
 // when CheckDir is successful due to I/O errors.
 func CheckDir(dir string) (CheckedFiles, error) {
 	// List files (as CreateFromDir would) and check which ones are omitted
@@ -363,13 +364,13 @@ func CheckDir(dir string) (CheckedFiles, error) {
 // CheckZip reports whether the files contained in a zip file satisfy the name
 // and size constraints listed in the package documentation.
 //
-// CheckZip returns an error if the returned CheckedFiles does not describe
-// a valid module zip file (according to CheckedFiles.Err). The returned
+// CheckZip returns an error if the returned [CheckedFiles] does not describe
+// a valid module zip file (according to [CheckedFiles.Err]). The returned
 // CheckedFiles is still populated when an error is returned. CheckZip will
 // also return an error if the module path or version is malformed or if it
 // encounters an error reading the zip file.
 //
-// Note that CheckZip does not read individual files, so Unzip may still fail
+// Note that CheckZip does not read individual files, so [Unzip] may still fail
 // when CheckZip is successful due to I/O errors.
 func CheckZip(m module.Version, zipFile string) (CheckedFiles, error) {
 	f, err := os.Open(zipFile)
@@ -477,7 +478,7 @@ func checkZip(m module.Version, f *os.File) (*zip.Reader, CheckedFiles, error) {
 // and writes it to w.
 //
 // Create verifies the restrictions described in the package documentation
-// and should not produce an archive that Unzip cannot extract. Create does not
+// and should not produce an archive that [Unzip] cannot extract. Create does not
 // include files in the output archive if they don't belong in the module zip.
 // In particular, Create will not include files in modules found in
 // subdirectories, most files in vendor directories, or irregular files (such
@@ -544,12 +545,12 @@ func Create(w io.Writer, m module.Version, files []File) (err error) {
 // a directory, dir. The zip content is written to w.
 //
 // CreateFromDir verifies the restrictions described in the package
-// documentation and should not produce an archive that Unzip cannot extract.
+// documentation and should not produce an archive that [Unzip] cannot extract.
 // CreateFromDir does not include files in the output archive if they don't
 // belong in the module zip. In particular, CreateFromDir will not include
 // files in modules found in subdirectories, most files in vendor directories,
 // or irregular files (such as symbolic links) in the output archive.
-// Additionally, unlike Create, CreateFromDir will not include directories
+// Additionally, unlike [Create], CreateFromDir will not include directories
 // named ".bzr", ".git", ".hg", or ".svn".
 func CreateFromDir(w io.Writer, m module.Version, dir string) (err error) {
 	defer func() {
@@ -581,8 +582,8 @@ func CreateFromDir(w io.Writer, m module.Version, dir string) (err error) {
 // "sub/dir". To create a zip from the base of the repository, pass an empty
 // string.
 //
-// If CreateFromVCS returns UnrecognizedVCSError, consider falling back to
-// CreateFromDir.
+// If CreateFromVCS returns [UnrecognizedVCSError], consider falling back to
+// [CreateFromDir].
 func CreateFromVCS(w io.Writer, m module.Version, repoRoot, revision, subdir string) (err error) {
 	defer func() {
 		if zerr, ok := err.(*zipError); ok {