From dc1be2d5b8abc34991a649f7499f9f673e36bb46 Mon Sep 17 00:00:00 2001 From: Aaron Jacobs Date: Tue, 3 Jan 2017 10:44:49 +1100 Subject: [PATCH] Update documentation for Go style. --- connection.go | 15 ++++++++------- fuseops/simple_types.go | 40 +++++++++++++++++++++------------------- mount.go | 7 ++++--- mounted_file_system.go | 13 +++++++------ unmount.go | 4 ++-- 5 files changed, 42 insertions(+), 37 deletions(-) diff --git a/connection.go b/connection.go index 0cca553..0f8a13f 100644 --- a/connection.go +++ b/connection.go @@ -55,7 +55,8 @@ var contextKey interface{} = contextKeyType(0) // Reading a page at a time is a drag. Ask for a larger size. const maxReadahead = 1 << 20 -// A connection to the fuse kernel process. +// Connection represents a connection to the fuse kernel process. It is used to +// receive and reply to requests from the kernel. type Connection struct { cfg MountConfig debugLogger *log.Logger @@ -115,7 +116,7 @@ func newConnection( return } -// Do the work necessary to cause the mount process to complete. +// Init performs the work necessary to cause the mount process to complete. func (c *Connection) Init() (err error) { // Read the init op. ctx, op, err := c.ReadOp() @@ -360,9 +361,9 @@ func (c *Connection) writeMessage(msg []byte) (err error) { return } -// Read the next op from the kernel process, returning the op and a context -// that should be used for work related to the op. Return io.EOF if the kernel -// has closed the connection. +// ReadOp consumes the next op from the kernel process, returning the op and a +// context that should be used for work related to the op. It returns io.EOF if +// the kernel has closed the connection. // // If err != nil, the user is responsible for later calling c.Reply with the // returned context. @@ -443,8 +444,8 @@ func (c *Connection) shouldLogError( return true } -// Reply to an op previously read using ReadOp, with the supplied error (or nil -// if successful). The context must be the context returned by ReadOp. +// Reply replies to an op previously read using ReadOp, with the supplied error +// (or nil if successful). The context must be the context returned by ReadOp. // // LOCKS_EXCLUDED(c.mu) func (c *Connection) Reply(ctx context.Context, opErr error) { diff --git a/fuseops/simple_types.go b/fuseops/simple_types.go index d63d3e0..5f5cdbf 100644 --- a/fuseops/simple_types.go +++ b/fuseops/simple_types.go @@ -22,18 +22,19 @@ import ( "github.com/jacobsa/fuse/internal/fusekernel" ) -// A 64-bit number used to uniquely identify a file or directory in the file -// system. File systems may mint inode IDs with any value except for +// InodeID is a 64-bit number used to uniquely identify a file or directory in +// the file system. File systems may mint inode IDs with any value except for // RootInodeID. // // This corresponds to struct inode::i_no in the VFS layer. // (Cf. http://goo.gl/tvYyQt) type InodeID uint64 -// A distinguished inode ID that identifies the root of the file system, e.g. -// in an OpenDirOp or LookUpInodeOp. Unlike all other inode IDs, which are -// minted by the file system, the FUSE VFS layer may send a request for this ID -// without the file system ever having referenced it in a previous response. +// RootInodeID is a distinguished inode ID that identifies the root of the file +// system, e.g. in an OpenDirOp or LookUpInodeOp. Unlike all other inode IDs, +// which are minted by the file system, the FUSE VFS layer may send a request +// for this ID without the file system ever having referenced it in a previous +// response. const RootInodeID = 1 func init() { @@ -55,8 +56,8 @@ func init() { } } -// Attributes for a file or directory inode. Corresponds to struct inode (cf. -// http://goo.gl/tvYyQt). +// InodeAttributes contains attributes for a file or directory inode. It +// corresponds to struct inode (cf. http://goo.gl/tvYyQt). type InodeAttributes struct { Size uint64 @@ -107,9 +108,10 @@ func (a *InodeAttributes) DebugString() string { a.Gid) } -// A generation number for an inode. Irrelevant for file systems that won't be -// exported over NFS. For those that will and that reuse inode IDs when they -// become free, the generation number must change when an ID is reused. +// GenerationNumber represents a generation of an inode. It is irrelevant for +// file systems that won't be exported over NFS. For those that will and that +// reuse inode IDs when they become free, the generation number must change +// when an ID is reused. // // This corresponds to struct inode::i_generation in the VFS layer. // (Cf. http://goo.gl/tvYyQt) @@ -124,20 +126,20 @@ func (a *InodeAttributes) DebugString() string { // type GenerationNumber uint64 -// An opaque 64-bit number used to identify a particular open handle to a file -// or directory. +// HandleID is an opaque 64-bit number used to identify a particular open +// handle to a file or directory. // // This corresponds to fuse_file_info::fh. type HandleID uint64 -// An offset into an open directory handle. This is opaque to FUSE, and can be -// used for whatever purpose the file system desires. See notes on -// ReadDirOp.Offset for details. +// DirOffset is an offset into an open directory handle. This is opaque to +// FUSE, and can be used for whatever purpose the file system desires. See +// notes on ReadDirOp.Offset for details. type DirOffset uint64 -// Information about a child inode within its parent directory. Shared by -// LookUpInodeOp, MkDirOp, CreateFileOp, etc. Consumed by the kernel in order -// to set up a dcache entry. +// ChildInodeEntry contains information about a child inode within its parent +// directory. It is shared by LookUpInodeOp, MkDirOp, CreateFileOp, etc, and is +// consumed by the kernel in order to set up a dcache entry. type ChildInodeEntry struct { // The ID of the child inode. The file system must ensure that the returned // inode ID remains valid until a later ForgetInodeOp. diff --git a/mount.go b/mount.go index 6227617..1226847 100644 --- a/mount.go +++ b/mount.go @@ -21,7 +21,8 @@ import ( "golang.org/x/net/context" ) -// A type that knows how to serve ops read from a connection. +// Server is an interface for any type that knows how to serve ops read from a +// connection. type Server interface { // Read and serve ops from the supplied connection until EOF. Do not return // until all operations have been responded to. Must not be called more than @@ -29,8 +30,8 @@ type Server interface { ServeOps(*Connection) } -// Attempt to mount a file system on the given directory, using the supplied -// Server to serve connection requests. This function blocks until the file +// Mount attempts to mount a file system on the given directory, using the +// supplied Server to serve connection requests. It blocks until the file // system is successfully mounted. func Mount( dir string, diff --git a/mounted_file_system.go b/mounted_file_system.go index 45811d9..1e300e8 100644 --- a/mounted_file_system.go +++ b/mounted_file_system.go @@ -16,8 +16,8 @@ package fuse import "golang.org/x/net/context" -// A struct representing the status of a mount operation, with a method that -// waits for unmounting. +// MountedFileSystem represents the status of a mount operation, with a method +// that waits for unmounting. type MountedFileSystem struct { dir string @@ -26,15 +26,16 @@ type MountedFileSystem struct { joinStatusAvailable chan struct{} } -// Return the directory on which the file system is mounted (or where we +// Dir returns the directory on which the file system is mounted (or where we // attempted to mount it.) func (mfs *MountedFileSystem) Dir() string { return mfs.dir } -// Block until a mounted file system has been unmounted. Do not return -// successfully until all ops read from the connection have been responded to -// (i.e. the file system server has finished processing all in-flight ops). +// Join blocks until a mounted file system has been unmounted. It does not +// return successfully until all ops read from the connection have been +// responded to (i.e. the file system server has finished processing all +// in-flight ops). // // The return value will be non-nil if anything unexpected happened while // serving. May be called multiple times. diff --git a/unmount.go b/unmount.go index a9d78e0..e63baf7 100644 --- a/unmount.go +++ b/unmount.go @@ -14,8 +14,8 @@ package fuse -// Attempt to unmount the file system whose mount point is the supplied -// directory. +// Unmount attempts to unmount the file system whose mount point is the +// supplied directory. func Unmount(dir string) error { return unmount(dir) }