Merge pull request #275 from gotestyourself/fs-add-godoc-links

fs: add go doc links

Author: dnephin

fs/manifest.go

@@ -55,9 +55,9 @@ type dirEntry interface {
 	Type() string
 }
 
-// ManifestFromDir creates a Manifest by reading the directory at path. The
+// ManifestFromDir creates a [Manifest] by reading the directory at path. The
 // manifest stores the structure and properties of files in the directory.
-// ManifestFromDir can be used with Equal to compare two directories.
+// ManifestFromDir can be used with [Equal] to compare two directories.
 func ManifestFromDir(t assert.TestingT, path string) Manifest {
 	if ht, ok := t.(helperT); ok {
 		ht.Helper()

fs/ops.go

@@ -14,9 +14,9 @@ import (
 
 const defaultFileMode = 0644
 
-// PathOp is a function which accepts a Path and performs an operation on that
-// path. When called with real filesystem objects (File or Dir) a PathOp modifies
-// the filesystem at the path. When used with a Manifest object a PathOp updates
+// PathOp is a function which accepts a [Path] and performs an operation on that
+// path. When called with real filesystem objects ([File] or [Dir]) a PathOp modifies
+// the filesystem at the path. When used with a [Manifest] object a PathOp updates
 // the manifest to expect a value.
 type PathOp func(path Path) error
 
@@ -38,7 +38,7 @@ type manifestDirectory interface {
 	AddDirectory(path string, ops ...PathOp) error
 }
 
-// WithContent writes content to a file at Path
+// WithContent writes content to a file at [Path]
 func WithContent(content string) PathOp {
 	return func(path Path) error {
 		if m, ok := path.(manifestFile); ok {
@@ -49,7 +49,7 @@ func WithContent(content string) PathOp {
 	}
 }
 
-// WithBytes write bytes to a file at Path
+// WithBytes write bytes to a file at [Path]
 func WithBytes(raw []byte) PathOp {
 	return func(path Path) error {
 		if m, ok := path.(manifestFile); ok {
@@ -60,7 +60,7 @@ func WithBytes(raw []byte) PathOp {
 	}
 }
 
-// WithReaderContent copies the reader contents to the file at Path
+// WithReaderContent copies the reader contents to the file at [Path]
 func WithReaderContent(r io.Reader) PathOp {
 	return func(path Path) error {
 		if m, ok := path.(manifestFile); ok {
@@ -77,7 +77,7 @@ func WithReaderContent(r io.Reader) PathOp {
 	}
 }
 
-// AsUser changes ownership of the file system object at Path
+// AsUser changes ownership of the file system object at [Path]
 func AsUser(uid, gid int) PathOp {
 	return func(path Path) error {
 		if m, ok := path.(manifestResource); ok {
@@ -132,7 +132,7 @@ func WithFiles(files map[string]string) PathOp {
 	}
 }
 
-// FromDir copies the directory tree from the source path into the new Dir
+// FromDir copies the directory tree from the source path into the new [Dir]
 func FromDir(source string) PathOp {
 	return func(path Path) error {
 		if _, ok := path.(manifestDirectory); ok {
@@ -142,7 +142,7 @@ func FromDir(source string) PathOp {
 	}
 }
 
-// WithDir creates a subdirectory in the directory at path. Additional PathOp
+// WithDir creates a subdirectory in the directory at path. Additional [PathOp]
 // can be used to modify the subdirectory
 func WithDir(name string, ops ...PathOp) PathOp {
 	const defaultMode = 0755
@@ -161,7 +161,7 @@ func WithDir(name string, ops ...PathOp) PathOp {
 	}
 }
 
-// Apply the PathOps to the File
+// Apply the PathOps to the [File]
 func Apply(t assert.TestingT, path Path, ops ...PathOp) {
 	if ht, ok := t.(helperT); ok {
 		ht.Helper()
@@ -178,7 +178,7 @@ func applyPathOps(path Path, ops []PathOp) error {
 	return nil
 }
 
-// WithMode sets the file mode on the directory or file at path
+// WithMode sets the file mode on the directory or file at [Path]
 func WithMode(mode os.FileMode) PathOp {
 	return func(path Path) error {
 		if m, ok := path.(manifestResource); ok {
@@ -241,7 +241,7 @@ func copyFile(source, dest string) error {
 // WithSymlink creates a symlink in the directory which links to target.
 // Target must be a path relative to the directory.
 //
-// Note: the argument order is the inverse of os.Symlink to be consistent with
+// Note: the argument order is the inverse of [os.Symlink] to be consistent with
 // the other functions in this package.
 func WithSymlink(path, target string) PathOp {
 	return func(root Path) error {
@@ -255,7 +255,7 @@ func WithSymlink(path, target string) PathOp {
 // WithHardlink creates a link in the directory which links to target.
 // Target must be a path relative to the directory.
 //
-// Note: the argument order is the inverse of os.Link to be consistent with
+// Note: the argument order is the inverse of [os.Link] to be consistent with
 // the other functions in this package.
 func WithHardlink(path, target string) PathOp {
 	return func(root Path) error {

fs/path.go

@@ -77,8 +77,8 @@ func (p *directoryPath) AddDirectory(path string, ops ...PathOp) error {
 	return applyPathOps(exp, ops)
 }
 
-// Expected returns a Manifest with a directory structured created by ops. The
-// PathOp operations are applied to the manifest as expectations of the
+// Expected returns a [Manifest] with a directory structured created by ops. The
+// [PathOp] operations are applied to the manifest as expectations of the
 // filesystem structure and properties.
 func Expected(t assert.TestingT, ops ...PathOp) Manifest {
 	if ht, ok := t.(helperT); ok {
@@ -125,7 +125,7 @@ func normalizeID(id int) uint32 {
 
 var anyFileContent = io.NopCloser(bytes.NewReader(nil))
 
-// MatchAnyFileContent is a PathOp that updates a Manifest so that the file
+// MatchAnyFileContent is a [PathOp] that updates a [Manifest] so that the file
 // at path may contain any content.
 func MatchAnyFileContent(path Path) error {
 	if m, ok := path.(*filePath); ok {
@@ -134,7 +134,7 @@ func MatchAnyFileContent(path Path) error {
 	return nil
 }
 
-// MatchContentIgnoreCarriageReturn is a PathOp that ignores cariage return
+// MatchContentIgnoreCarriageReturn is a [PathOp] that ignores cariage return
 // discrepancies.
 func MatchContentIgnoreCarriageReturn(path Path) error {
 	if m, ok := path.(*filePath); ok {
@@ -145,7 +145,7 @@ func MatchContentIgnoreCarriageReturn(path Path) error {
 
 const anyFile = "*"
 
-// MatchExtraFiles is a PathOp that updates a Manifest to allow a directory
+// MatchExtraFiles is a [PathOp] that updates a [Manifest] to allow a directory
 // to contain unspecified files.
 func MatchExtraFiles(path Path) error {
 	if m, ok := path.(*directoryPath); ok {
@@ -156,14 +156,14 @@ func MatchExtraFiles(path Path) error {
 
 // CompareResult is the result of comparison.
 //
-// See gotest.tools/assert/cmp.StringResult for a convenient implementation of
+// See [gotest.tools/v3/assert/cmp.StringResult] for a convenient implementation of
 // this interface.
 type CompareResult interface {
 	Success() bool
 	FailureMessage() string
 }
 
-// MatchFileContent is a PathOp that updates a Manifest to use the provided
+// MatchFileContent is a [PathOp] that updates a [Manifest] to use the provided
 // function to determine if a file's content matches the expectation.
 func MatchFileContent(f func([]byte) CompareResult) PathOp {
 	return func(path Path) error {
@@ -174,7 +174,7 @@ func MatchFileContent(f func([]byte) CompareResult) PathOp {
 	}
 }
 
-// MatchFilesWithGlob is a PathOp that updates a Manifest to match files using
+// MatchFilesWithGlob is a [PathOp] that updates a [Manifest] to match files using
 // glob pattern, and check them using the ops.
 func MatchFilesWithGlob(glob string, ops ...PathOp) PathOp {
 	return func(path Path) error {
@@ -188,7 +188,7 @@ func MatchFilesWithGlob(glob string, ops ...PathOp) PathOp {
 // anyFileMode is represented by uint32_max
 const anyFileMode os.FileMode = 4294967295
 
-// MatchAnyFileMode is a PathOp that updates a Manifest so that the resource at path
+// MatchAnyFileMode is a [PathOp] that updates a [Manifest] so that the resource at path
 // will match any file mode.
 func MatchAnyFileMode(path Path) error {
 	if m, ok := path.(manifestResource); ok {

fs/report.go

@@ -17,9 +17,9 @@ import (
 // Equal compares a directory to the expected structured described by a manifest
 // and returns success if they match. If they do not match the failure message
 // will contain all the differences between the directory structure and the
-// expected structure defined by the Manifest.
+// expected structure defined by the [Manifest].
 //
-// Equal is a cmp.Comparison which can be used with assert.Assert().
+// Equal is a [cmp.Comparison] which can be used with [gotest.tools/v3/assert.Assert].
 func Equal(path string, expected Manifest) cmp.Comparison {
 	return func() cmp.Result {
 		actual, err := manifestFromDir(path)