fs: more godoc

Change-Id: I1fe9bf5c77a332002b3b0a15b75853102549b511

fs/api.go

@@ -33,7 +33,6 @@
 // initialized by calling NewInode or NewPersistentInode before being
 // manipulated further, eg.
 //
-//
 //  type myNode struct {
 //     Inode
 //  }
@@ -83,6 +82,9 @@ import (
 
 // InodeEmbedder is an interface for structs that embed Inode.
 //
+// InodeEmbedder objects usually should implement some of the NodeXxxx
+// interfaces, to provide user-defined file system behaviors.
+//
 // In general, if an InodeEmbedder does not implement specific
 // filesystem methods, the filesystem will react as if it is a
 // read-only filesystem with a predefined tree structure. See
@@ -358,10 +360,17 @@ type NodeRenamer interface {
 	Rename(ctx context.Context, name string, newParent InodeEmbedder, newName string, flags uint32) syscall.Errno
 }
 
-// FileHandle is a resource identifier for opened files.  FileHandles
-// are useful in two cases: First, if the underlying storage systems
-// needs a handle for reading/writing. See the function
-// `NewLoopbackFile` for an example. Second, it is useful for
+// FileHandle is a resource identifier for opened files. Usually, a
+// FileHandle should implement some of the FileXxxx interfaces.
+//
+// All of the FileXxxx operations can also be implemented at the
+// InodeEmbedder level, for example, one can implement NodeReader
+// instead of FileReader.
+//
+// FileHandles are useful in two cases: First, if the underlying
+// storage systems needs a handle for reading/writing. This is the
+// case with Unix system calls, which need a file descriptor (See also
+// the function `NewLoopbackFile`). Second, it is useful for
 // implementing files whose contents are not tied to an inode. For
 // example, a file like `/proc/interrupts` has no fixed content, but
 // changes on each open call. This means that each file handle must

fs/inmemory_example_test.go

@@ -55,19 +55,24 @@ func (root *inMemoryFS) OnAdd(ctx context.Context) {
 			p = ch
 		}
 
+		// Make a file out of the content bytes. This type
+		// provides the open/read/flush methods.
+		embedder := &fs.MemRegularFile{
+			Data: []byte(content),
+		}
+
 		// Create the file. The Inode must be persistent,
 		// because its life time is not under control of the
 		// kernel.
-		child := p.NewPersistentInode(ctx, &fs.MemRegularFile{
-			Data: []byte(content),
-		}, fs.StableAttr{})
+		child := p.NewPersistentInode(ctx, embedder, fs.StableAttr{})
 
 		// And add it
 		p.AddChild(base, child, true)
 	}
 }
 
-// This demonstrates how to build a file system in memory.
+// This demonstrates how to build a file system in memory. The
+// read/write logic for the file is provided by the MemRegularFile type.
 func Example() {
 	// This is where we'll mount the FS
 	mntDir, _ := ioutil.TempDir("", "")

fs/loopback.go

@@ -372,7 +372,8 @@ func (n *loopbackNode) Setattr(ctx context.Context, f FileHandle, in *fuse.SetAt
 }
 
 // NewLoopback returns a root node for a loopback file system whose
-// root is at the given root.
+// root is at the given root. This node implements all NodeXxxxer
+// operations available.
 func NewLoopbackRoot(root string) (InodeEmbedder, error) {
 	var st syscall.Stat_t
 	err := syscall.Stat(root, &st)

fs/mem.go

@@ -13,7 +13,6 @@ import (
 
 // MemRegularFile is a filesystem node that holds a read-only data
 // slice in memory.
-
 type MemRegularFile struct {
 	Inode
 	Data []byte