doc: document DocIDReader, and some Index bits

index.go

@@ -160,7 +160,10 @@ type Index interface {
 	NewBatch() *Batch
 	Batch(b *Batch) error
 
+	// Document returns specified document or nil if the document is not
+	// indexed or stored.
 	Document(id string) (*document.Document, error)
+	// DocCount returns the number of indexed or stored documents.
 	DocCount() (uint64, error)
 
 	Search(req *SearchRequest) (*SearchResult, error)
@@ -185,6 +188,8 @@ type Index interface {
 	SetInternal(key, val []byte) error
 	DeleteInternal(key []byte) error
 
+	// Advanced returns the indexer and data store, exposing lower level
+	// methods to enumerate records and access data.
 	Advanced() (index.Index, store.KVStore, error)
 }
 

index/index.go

@@ -35,6 +35,8 @@ type Index interface {
 	DumpDoc(id string) chan interface{}
 	DumpFields() chan interface{}
 
+	// Reader returns a low-level accessor on the index data. Close it to
+	// release associated resources.
 	Reader() (IndexReader, error)
 
 	Stats() json.Marshaler
@@ -44,6 +46,10 @@ type Index interface {
 
 type IndexReader interface {
 	TermFieldReader(term []byte, field string) (TermFieldReader, error)
+
+	// DocIDReader returns an iterator over indexed or stored documents which
+	// identifiers are greater than or equal to start and smaller than end. The
+	// caller must close returned instance to release associated resources.
 	DocIDReader(start, end string) (DocIDReader, error)
 
 	FieldDict(field string) (FieldDict, error)
@@ -99,8 +105,17 @@ type FieldDict interface {
 	Close() error
 }
 
+// DocIDReader is the interface exposing enumeration of indexed or stored
+// documents identifiers. Close the reader to release associated resources.
 type DocIDReader interface {
+	// Next returns the next document identifier in ascending lexicographic
+	// byte order, or io.EOF when the end of the sequence is reached.
 	Next() (string, error)
+
+	// Advance resets the iteration to the first identifier greater than or
+	// equal to ID. If ID is greater than or equal to the end of the range,
+	// Next() call will return io.EOF. If ID is smaller than the start of the
+	// range, the behaviour depends on the store implementation.
 	Advance(ID string) (string, error)
 	Close() error
 }