From baa5c2d058db25484c20d76985ba394e73176132 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Mengu=C3=A9?= Date: Mon, 5 Jun 2023 14:59:04 +0200 Subject: [PATCH] all: add godoc links Change-Id: Ic9532893740b9952ca429106b3c373cc14d0383e Reviewed-on: https://go-review.googlesource.com/c/mod/+/500875 Run-TryBot: Bryan Mills TryBot-Result: Gopher Robot Reviewed-by: Bryan Mills Reviewed-by: Dmitri Shuralyov Reviewed-by: Oleksandr Redko Auto-Submit: Bryan Mills --- README.md | 3 ++- internal/lazyregexp/lazyre.go | 2 +- modfile/read.go | 2 +- modfile/rule.go | 20 +++++++-------- modfile/work.go | 4 +-- module/module.go | 30 +++++++++++----------- module/pseudo.go | 2 +- semver/semver.go | 6 ++--- sumdb/client.go | 14 +++++------ sumdb/note/note.go | 38 ++++++++++++++-------------- sumdb/server.go | 4 +-- sumdb/storage/mem.go | 2 +- sumdb/storage/storage.go | 2 +- sumdb/test.go | 6 ++--- sumdb/tlog/tile.go | 8 +++--- sumdb/tlog/tlog.go | 6 ++--- zip/zip.go | 47 ++++++++++++++++++----------------- 17 files changed, 99 insertions(+), 97 deletions(-) diff --git a/README.md b/README.md index 07d44f0..94da72d 100644 --- a/README.md +++ b/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 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 @@ 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 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 @@ 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 { 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 @@ 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 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 @@ 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() { 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 @@ 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'. // 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 @@ 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)) } 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 @@ 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)) } 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 @@ 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)") 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 "++". // -// 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+++". // 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 { 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 @@ 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 } 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 @@ 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. 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 @@ 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. 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 @@ 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) 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 @@ 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 { 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 @@ 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) { 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 "@/", // where "" is the module path and "" 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 // "@/" 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 "@/go.mod" or // "@/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 {