comments and name improvements

decode/decode.go

@@ -22,7 +22,9 @@ func (d *Decoder) SetMapper(maps collect.MapFactory) {
 	d.collector.maps = maps
 }
 
-// record comment blocks
+// pass a valid target for document level comments
+// a nil disables comment collection
+// ( comments are disabled by default )
 func (d *Decoder) UseNotes(b *note.Book) {
 	d.docBlock = b
 	d.collector.keepComments = b != nil
@@ -218,7 +220,7 @@ func (d *Decoder) newKey(at token.Pos, key string) (err error) {
 	} else if e := d.out.setKey(at.Y, key); e != nil {
 		err = e
 	} else {
-		d.out.NextKey()
+		d.out.NextTerm()
 		d.state = d.waitForValue // same as current state.
 	}
 	return
@@ -248,7 +250,6 @@ func (d *Decoder) newComment(defaultType note.Type, at token.Pos, str string) (e
 				d.out.Comment(noteType, str)
 			}
 		}
-
 	}
 	return
 }

decoder.go

@@ -50,8 +50,10 @@ func (d *Decoder) SetSequencer(seq collect.SequenceFactory) {
 	d.inner.SetSequencer(seq)
 }
 
-// control the creation of comment blocks for the upcoming Decode.
-// the default is to discard comments.
+// pass a valid target for collecting document level comments
+// during an upcoming call to Decode.
+// the default behavior is to discard comments.
+// ( passing nil will also discard them. )
 func (d *Decoder) UseNotes(b *note.Book) {
 	d.inner.UseNotes(b)
 }

note/book.go

@@ -2,7 +2,8 @@ package note
 
 import "strings"
 
-// record comment block
+// collects comments to generate a comment block
+// ( during document decoding )
 type Book struct {
 	book content
 }
@@ -17,9 +18,9 @@ func (p *Book) EndCollection() {
 		p.book.EndCollection()
 	}
 }
-func (p *Book) NextKey() {
+func (p *Book) NextTerm() {
 	if p.book.buf != nil {
-		p.book.NextKey()
+		p.book.NextTerm()
 	}
 }
 func (p *Book) Comment(kind Type, str string) {

note/content.go

@@ -34,6 +34,9 @@ type bookState struct {
 
 func (b *content) BeginCollection(buf *strings.Builder) {
 	b.buf = buf
+	// if there is a (footer or prefix) comment pending
+	// steal it from the shared buffer, and use it as
+	// the header of the first element.
 	if buf.Len() > 0 {
 		appendLine(&b.out, buf.String())
 		buf.Reset()
@@ -57,7 +60,7 @@ func (b *content) EndCollection() {
 }
 
 // new key in this block
-func (b *content) NextKey() {
+func (b *content) NextTerm() {
 	// note: if there's a sub-collection
 	// its begin() will have stolen our buffer away
 	b.nextKeys++
@@ -110,7 +113,7 @@ func (b *content) flushTerm() {
 	//
 	// FirstKey: # inline prefix
 	// # header for next key
-	// NextKey:
+	// NextTerm:
 	//
 	if b.buf.Len() > 0 {
 		b.writeKeys()

note/note.go

@@ -2,12 +2,26 @@ package note
 
 import "strings"
 
-// a comment block
+// a comment block generator
+// see Nothing ( which discards comments )
+// and Book ( which compiles comments into a comment block. )
 type Taker interface {
+	// start recording comments for a new sequence, mapping, or document.
+	// every collection in a document must share the same string builder;
+	// but each should probably have its own unique taker.
+	// passing nil will disable comment collection.
 	BeginCollection(*strings.Builder)
+	// record a comment
 	Comment(Type, string)
-	NextKey()
+	// separates comments for each term within a collection
+	// ( terms in a sequence are indicated by a dash
+	//   terms in a mapping are indicated by a signature style key )
+	NextTerm()
+	// stop recording comments for this collection
+	// probably best to not reuse the taker after this call.
 	EndCollection()
-	// return true
+	// return the unified comment block for a collection.
+	// initially true, if BeginCollection had been passed a valid string buffer.
+	// subsequent calls may return false.
 	Resolve() (ret string, okay bool)
 }

note/noteType.go

@@ -1,5 +1,7 @@
 package note
 
+// differentiates different comment types
+// as described in the package README.
 type Type int
 
 const (
@@ -16,6 +18,7 @@ const (
 	Footer
 )
 
+// is this one of the two prefix types?
 func (n Type) Prefix() (okay bool) {
 	switch n {
 	case Prefix, PrefixInline:
@@ -24,6 +27,7 @@ func (n Type) Prefix() (okay bool) {
 	return
 }
 
+// is this one of the two suffix types?
 func (n Type) Suffix() (okay bool) {
 	switch n {
 	case Suffix, SuffixInline:

note/nothing.go

@@ -7,6 +7,6 @@ type Nothing struct{}
 
 func (Nothing) BeginCollection(buf *strings.Builder) {}
 func (Nothing) EndCollection()                       {}
-func (Nothing) NextKey()                             {}
+func (Nothing) NextTerm()                            {}
 func (Nothing) Comment(Type, string)                 {}
 func (Nothing) Resolve() (_ string, _ bool)          { return }