Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fs: add go doc links #275

Merged
merged 1 commit into from
Sep 16, 2023
Merged

fs: add go doc links #275

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions fs/manifest.go
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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