Skip to content

Commit

Permalink
fs: add go doc links
Browse files Browse the repository at this point in the history
  • Loading branch information
dolmen authored and dnephin committed Sep 16, 2023
1 parent a80f057 commit 9af8f4e
Show file tree
Hide file tree
Showing 4 changed files with 26 additions and 26 deletions.
4 changes: 2 additions & 2 deletions fs/manifest.go
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
26 changes: 13 additions & 13 deletions fs/ops.go
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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 {
Expand Down Expand Up @@ -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 {
Expand All @@ -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
Expand All @@ -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()
Expand All @@ -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 {
Expand Down Expand Up @@ -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 {
Expand All @@ -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 {
Expand Down
18 changes: 9 additions & 9 deletions fs/path.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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 {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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 {
Expand Down
4 changes: 2 additions & 2 deletions fs/report.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down

0 comments on commit 9af8f4e

Please sign in to comment.