Commit dc1be2d5 authored by Aaron Jacobs's avatar Aaron Jacobs

Update documentation for Go style.

parent 2642d571
......@@ -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) {
......
......@@ -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.
......
......@@ -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,
......
......@@ -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.
......
......@@ -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)
}
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment