From f5f97e1c51adb3046b423dc4d0dd9732bcfbd64c Mon Sep 17 00:00:00 2001
From: ForrestWeston <forrest@protocol.ai>
Date: Mon, 22 Jan 2018 14:51:46 -0800
Subject: [PATCH] docs for mfs system method impls

License: MIT
Signed-off-by: ForrestWeston <forrest@protocol.ai>
---
 mfs/system.go | 27 +++++++++++++++++----------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/mfs/system.go b/mfs/system.go
index 28875d3b38aa..319ba3020c96 100644
--- a/mfs/system.go
+++ b/mfs/system.go
@@ -41,19 +41,19 @@ const (
 	TDir
 )
 
-// FSNode represents any node (directory, root, or file) in the mfs filesystem
+// FSNode represents any node (directory, root, or file) in the mfs filesystem.
 type FSNode interface {
 	GetNode() (node.Node, error)
 	Flush() error
 	Type() NodeType
 }
 
-// Root represents the root of a filesystem tree
+// Root represents the root of a filesystem tree.
 type Root struct {
-	// node is the merkledag root
+	// node is the merkledag root.
 	node *dag.ProtoNode
 
-	// val represents the node. It can either be a File or a Directory
+	// val represents the node. It can either be a File or a Directory.
 	val FSNode
 
 	repub *Republisher
@@ -63,9 +63,10 @@ type Root struct {
 	Type string
 }
 
+// PubFunc is the function used by the `publish()` method.
 type PubFunc func(context.Context, *cid.Cid) error
 
-// newRoot creates a new Root and starts up a republisher routine for it
+// NewRoot creates a new Root and starts up a republisher routine for it.
 func NewRoot(parent context.Context, ds dag.DAGService, node *dag.ProtoNode, pf PubFunc) (*Root, error) {
 
 	var repub *Republisher
@@ -107,10 +108,13 @@ func NewRoot(parent context.Context, ds dag.DAGService, node *dag.ProtoNode, pf
 	return root, nil
 }
 
+// GetValue returns the value of Root.
 func (kr *Root) GetValue() FSNode {
 	return kr.val
 }
 
+// Flush signals that an update has occurred since the last publish,
+// and updates the Root republisher.
 func (kr *Root) Flush() error {
 	nd, err := kr.GetValue().GetNode()
 	if err != nil {
@@ -154,7 +158,7 @@ func (kr *Root) FlushMemFree(ctx context.Context) error {
 }
 
 // closeChild implements the childCloser interface, and signals to the publisher that
-// there are changes ready to be published
+// there are changes ready to be published.
 func (kr *Root) closeChild(name string, nd node.Node, sync bool) error {
 	c, err := kr.dserv.Add(nd)
 	if err != nil {
@@ -181,7 +185,7 @@ func (kr *Root) Close() error {
 	return nil
 }
 
-// Republisher manages when to publish a given entry
+// Republisher manages when to publish a given entry.
 type Republisher struct {
 	TimeoutLong  time.Duration
 	TimeoutShort time.Duration
@@ -198,7 +202,7 @@ type Republisher struct {
 }
 
 // NewRepublisher creates a new Republisher object to republish the given root
-// using the given short and long time intervals
+// using the given short and long time intervals.
 func NewRepublisher(ctx context.Context, pf PubFunc, tshort, tlong time.Duration) *Republisher {
 	ctx, cancel := context.WithCancel(ctx)
 	return &Republisher{
@@ -218,6 +222,8 @@ func (p *Republisher) setVal(c *cid.Cid) {
 	p.val = c
 }
 
+// WaitPub Returns immediately if `lastpub` value is consistent with the
+// current value `val`, else will block until `val` has been published.
 func (p *Republisher) WaitPub() {
 	p.lk.Lock()
 	consistent := p.lastpub == p.val
@@ -239,7 +245,7 @@ func (p *Republisher) Close() error {
 
 // Touch signals that an update has occurred since the last publish.
 // Multiple consecutive touches may extend the time period before
-// the next Publish occurs in order to more efficiently batch updates
+// the next Publish occurs in order to more efficiently batch updates.
 func (np *Republisher) Update(c *cid.Cid) {
 	np.setVal(c)
 	select {
@@ -248,7 +254,7 @@ func (np *Republisher) Update(c *cid.Cid) {
 	}
 }
 
-// Run is the main republisher loop
+// Run is the main republisher loop.
 func (np *Republisher) Run() {
 	for {
 		select {
@@ -284,6 +290,7 @@ func (np *Republisher) Run() {
 	}
 }
 
+// publish calls the `PubFunc`.
 func (np *Republisher) publish(ctx context.Context) error {
 	np.lk.Lock()
 	topub := np.val