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