From b174c137fd621082573cb854375712a6e1e865be Mon Sep 17 00:00:00 2001
From: Patrick Mezard <patrick@mezard.eu>
Date: Sat, 17 Oct 2015 18:40:26 +0200
Subject: [PATCH] doc: document DocIDReader, and some Index bits

---
 index.go       |  5 +++++
 index/index.go | 15 +++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/index.go b/index.go
index 73c49d8b..fe68a44c 100644
--- a/index.go
+++ b/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)
 }
 
diff --git a/index/index.go b/index/index.go
index aa7b9a77..84469776 100644
--- a/index/index.go
+++ b/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
 }