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>
diff --git a/README.md b/README.md
index 07d44f0..94da72d 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,8 @@
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
diff --git a/internal/lazyregexp/lazyre.go b/internal/lazyregexp/lazyre.go
index 2681af3..150f887 100644
--- a/internal/lazyregexp/lazyre.go
+++ b/internal/lazyregexp/lazyre.go
@@ -13,7 +13,7 @@
"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
diff --git a/modfile/read.go b/modfile/read.go
index a503bc2..5b5bb5e 100644
--- a/modfile/read.go
+++ b/modfile/read.go
@@ -65,7 +65,7 @@
}
// 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 {
diff --git a/modfile/rule.go b/modfile/rule.go
index b4dd799..930b6c5 100644
--- a/modfile/rule.go
+++ b/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 @@
// 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 @@
}
// 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 @@
// 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
diff --git a/modfile/work.go b/modfile/work.go
index 75dc1c5..d7b9937 100644
--- a/modfile/work.go
+++ b/modfile/work.go
@@ -34,7 +34,7 @@
// 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 @@
}
// 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() {
diff --git a/module/module.go b/module/module.go
index e9dec6e..2a364b2 100644
--- a/module/module.go
+++ b/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 @@
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 @@
// 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) 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 @@
}
// 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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
}
// 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 @@
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 @@
}
// 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'.
//
diff --git a/module/pseudo.go b/module/pseudo.go
index f04ad37..9cf19d3 100644
--- a/module/pseudo.go
+++ b/module/pseudo.go
@@ -125,7 +125,7 @@
}
// 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))
}
diff --git a/semver/semver.go b/semver/semver.go
index a30a22b..9a2dfd3 100644
--- a/semver/semver.go
+++ b/semver/semver.go
@@ -140,7 +140,7 @@
// 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 @@
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 @@
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))
}
diff --git a/sumdb/client.go b/sumdb/client.go
index 1c1b029..aecdc68 100644
--- a/sumdb/client.go
+++ b/sumdb/client.go
@@ -19,7 +19,7 @@
)
// 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 @@
// 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 @@
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 @@
}
// 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 @@
// 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 @@
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)")
diff --git a/sumdb/note/note.go b/sumdb/note/note.go
index 8c22b19..db9865c 100644
--- a/sumdb/note/note.go
+++ b/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 @@
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) 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 @@
}
// 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 @@
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 @@
// 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 {
diff --git a/sumdb/server.go b/sumdb/server.go
index 899bd46..1e1779d 100644
--- a/sumdb/server.go
+++ b/sumdb/server.go
@@ -17,7 +17,7 @@
)
// 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 @@
// 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
}
diff --git a/sumdb/storage/mem.go b/sumdb/storage/mem.go
index 9b7823d..6cba011 100644
--- a/sumdb/storage/mem.go
+++ b/sumdb/storage/mem.go
@@ -11,7 +11,7 @@
"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.
diff --git a/sumdb/storage/storage.go b/sumdb/storage/storage.go
index 1806380..ed5df49 100644
--- a/sumdb/storage/storage.go
+++ b/sumdb/storage/storage.go
@@ -27,7 +27,7 @@
}
// 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.
diff --git a/sumdb/test.go b/sumdb/test.go
index c2755b8..fb77245 100644
--- a/sumdb/test.go
+++ b/sumdb/test.go
@@ -14,15 +14,15 @@
"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)
diff --git a/sumdb/tlog/tile.go b/sumdb/tlog/tile.go
index e4aeb14..857d487 100644
--- a/sumdb/tlog/tile.go
+++ b/sumdb/tlog/tile.go
@@ -28,7 +28,7 @@
// 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 @@
// 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 @@
// 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 @@
// 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 {
diff --git a/sumdb/tlog/tlog.go b/sumdb/tlog/tlog.go
index ae065f8..6a11a75 100644
--- a/sumdb/tlog/tlog.go
+++ b/sumdb/tlog/tlog.go
@@ -131,7 +131,7 @@
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 @@
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 @@
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) {
diff --git a/zip/zip.go b/zip/zip.go
index d890b99..574f83f 100644
--- a/zip/zip.go
+++ b/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 @@
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 @@
}
// 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 @@
// 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 @@
// 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 @@
// 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 @@
// "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 {
