Update documentation for Go style.

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) {

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.

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,

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.

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)
 }