improve go docs at the top level

part of blevesearch#79
abhishekdas29 · Aug 31, 2014 · 209f808 · 209f808
1 parent 862205f
commit 209f808
Show file tree

Hide file tree

Showing 21 changed files with 205 additions and 11 deletions.
diff --git a/config.go b/config.go
@@ -107,6 +107,7 @@ func newConfiguration() *configuration {
 	}
 }
 
+// Config contains library level configuration
 var Config *configuration
 
 func init() {

diff --git a/index.go b/index.go
@@ -13,20 +13,33 @@ import (
 	"github.com/blevesearch/bleve/document"
 )
 
+// A Batch groups together multiple Index and Delete
+// operations you would like performed at the same
+// time.
 type Batch map[string]interface{}
 
+// NewBatch creates a new empty batch.
 func NewBatch() Batch {
 	return make(Batch, 0)
 }
 
+// Index adds the specified index operation to the
+// batch.  NOTE: the bleve Index is not updated
+// until the batch is executed.
 func (b Batch) Index(id string, data interface{}) {
 	b[id] = data
 }
 
+// Delete adds the specified delete operation to the
+// batch.  NOTE: the bleve Index is not updated until
+// the batch is executed.
 func (b Batch) Delete(id string) {
 	b[id] = nil
 }
 
+// An Index implements all the indexing and searching
+// capabilities of bleve.  An Index can be created
+// using the New() and Open() methods.
 type Index interface {
 	Index(id string, data interface{}) error
 	Delete(id string) error
@@ -49,12 +62,15 @@ type Index interface {
 	Mapping() *IndexMapping
 }
 
+// A Classifier is an interface describing any object
+// which knows how to identify its own type.
 type Classifier interface {
 	Type() string
 }
 
 // New index at the specified path, must not exist.
-// The provided mapping will be used for all Index/Search operations.
+// The provided mapping will be used for all
+// Index/Search operations.
 func New(path string, mapping *IndexMapping) (Index, error) {
 	return newIndex(path, mapping)
 }

diff --git a/index_impl.go b/index_impl.go
@@ -209,10 +209,15 @@ func openIndex(path string) (*indexImpl, error) {
 	return &rv, nil
 }
 
+// Mapping returns the IndexMapping in use by this
+// Index.
 func (i *indexImpl) Mapping() *IndexMapping {
 	return i.m
 }
 
+// Index the object with the specified identifier.
+// The IndexMapping for this index will determine
+// how the object is indexed.
 func (i *indexImpl) Index(id string, data interface{}) error {
 	i.mutex.Lock()
 	defer i.mutex.Unlock()
@@ -233,6 +238,8 @@ func (i *indexImpl) Index(id string, data interface{}) error {
 	return nil
 }
 
+// Delete entries for the specified identifier from
+// the index.
 func (i *indexImpl) Delete(id string) error {
 	i.mutex.Lock()
 	defer i.mutex.Unlock()
@@ -248,6 +255,10 @@ func (i *indexImpl) Delete(id string) error {
 	return nil
 }
 
+// Batch executes multiple Index and Delete
+// operations at the same time.  There are often
+// significant performance benefits when performing
+// operations in a batch.
 func (i *indexImpl) Batch(b Batch) error {
 	i.mutex.Lock()
 	defer i.mutex.Unlock()
@@ -272,6 +283,10 @@ func (i *indexImpl) Batch(b Batch) error {
 	return i.i.Batch(ib)
 }
 
+// Document is used to find the values of all the
+// stored fields for a document in the index.  These
+// stored fields are put back into a Document object
+// and returned.
 func (i *indexImpl) Document(id string) (*document.Document, error) {
 	i.mutex.RLock()
 	defer i.mutex.RUnlock()
@@ -282,6 +297,8 @@ func (i *indexImpl) Document(id string) (*document.Document, error) {
 	return i.i.Document(id)
 }
 
+// DocCount returns the number of documents in the
+// index.
 func (i *indexImpl) DocCount() uint64 {
 	i.mutex.RLock()
 	defer i.mutex.RUnlock()
@@ -293,6 +310,8 @@ func (i *indexImpl) DocCount() uint64 {
 	return i.i.DocCount()
 }
 
+// Search executes a search request operation.
+// Returns a SearchResult object or an error.
 func (i *indexImpl) Search(req *SearchRequest) (*SearchResult, error) {
 	i.mutex.RLock()
 	defer i.mutex.RUnlock()
@@ -416,27 +435,36 @@ func (i *indexImpl) Search(req *SearchRequest) (*SearchResult, error) {
 	}, nil
 }
 
-func (i *indexImpl) DumpAll() chan interface{} {
+// Fields returns the name of all the fields this
+// Index has operated on.
+func (i *indexImpl) Fields() ([]string, error) {
 	i.mutex.RLock()
 	defer i.mutex.RUnlock()
 
 	if !i.open {
-		return nil
+		return nil, ERROR_INDEX_CLOSED
 	}
-
-	return i.i.DumpAll()
+	return i.i.Fields()
 }
 
-func (i *indexImpl) Fields() ([]string, error) {
+// DumpAll writes all index rows to a channel.
+// INTERNAL: do not rely on this function, it is
+// only intended to be used by the debug utilties
+func (i *indexImpl) DumpAll() chan interface{} {
 	i.mutex.RLock()
 	defer i.mutex.RUnlock()
 
 	if !i.open {
-		return nil, ERROR_INDEX_CLOSED
+		return nil
 	}
-	return i.i.Fields()
+
+	return i.i.DumpAll()
 }
 
+// DumpFields writes all field rows in the index
+// to a channel.
+// INTERNAL: do not rely on this function, it is
+// only intended to be used by the debug utilties
 func (i *indexImpl) DumpFields() chan interface{} {
 	i.mutex.RLock()
 	defer i.mutex.RUnlock()
@@ -447,6 +475,10 @@ func (i *indexImpl) DumpFields() chan interface{} {
 	return i.i.DumpFields()
 }
 
+// DumpDoc writes all rows in the index associated
+// with the specified identifier to a channel.
+// INTERNAL: do not rely on this function, it is
+// only intended to be used by the debug utilties
 func (i *indexImpl) DumpDoc(id string) chan interface{} {
 	i.mutex.RLock()
 	defer i.mutex.RUnlock()

diff --git a/mapping_document.go b/mapping_document.go
@@ -16,6 +16,19 @@ import (
 	"github.com/blevesearch/bleve/registry"
 )
 
+// A DocumentMapping describes how a type of document
+// should be indexed.
+// As documents can be hierarchical, named sub-sections
+// of documents are mapped using the same structure in
+// the Properties field.
+// Each value inside a document can be index 0 or more
+// ways.  These index entries are called fields and
+// are stored in the Fields field.
+// Entire sections of a document can be ignored or
+// excluded by setting Enabled to false.
+// If not explicitly mapped, default mapping operations
+// are used.  To disable this automatic handling, set
+// Dynamic to false.
 type DocumentMapping struct {
 	Enabled         bool                        `json:"enabled"`
 	Dynamic         bool                        `json:"dynamic"`
@@ -75,23 +88,32 @@ func (dm *DocumentMapping) documentMappingForPath(path string) *DocumentMapping
 	return current
 }
 
+// NewDocumentMapping returns a new document mapping
+// with all the default values.
 func NewDocumentMapping() *DocumentMapping {
 	return &DocumentMapping{
 		Enabled: true,
 		Dynamic: true,
 	}
 }
 
+// NewDocumentStaticMapping returns a new document
+// mapping that will not automatically index parts
+// of a document without an explicit mapping.
 func NewDocumentStaticMapping() *DocumentMapping {
 	return &DocumentMapping{
 		Enabled: true,
 	}
 }
 
+// NewDocumentDisabledMapping returns a new document
+// mapping that will not perform any indexing.
 func NewDocumentDisabledMapping() *DocumentMapping {
 	return &DocumentMapping{}
 }
 
+// Adds the provided DocumentMapping as a sub-mapping
+// for the specified named subsection.
 func (dm *DocumentMapping) AddSubDocumentMapping(property string, sdm *DocumentMapping) *DocumentMapping {
 	if dm.Properties == nil {
 		dm.Properties = make(map[string]*DocumentMapping)
@@ -100,6 +122,8 @@ func (dm *DocumentMapping) AddSubDocumentMapping(property string, sdm *DocumentM
 	return dm
 }
 
+// Adds the provided FieldMapping for this section
+// of the document.
 func (dm *DocumentMapping) AddFieldMapping(fm *FieldMapping) *DocumentMapping {
 	if dm.Fields == nil {
 		dm.Fields = make([]*FieldMapping, 0)
@@ -108,6 +132,8 @@ func (dm *DocumentMapping) AddFieldMapping(fm *FieldMapping) *DocumentMapping {
 	return dm
 }
 
+// UnmarshalJSON deserializes a JSON representation
+// of the DocumentMapping.
 func (dm *DocumentMapping) UnmarshalJSON(data []byte) error {
 	var tmp struct {
 		Enabled         *bool                       `json:"enabled"`

diff --git a/mapping_field.go b/mapping_field.go
@@ -13,6 +13,8 @@ import (
 	"github.com/blevesearch/bleve/document"
 )
 
+// A FieldMapping describes how a specific item
+// should be put into the index.
 type FieldMapping struct {
 	Name               *string `json:"name"`
 	Type               *string `json:"type"`
@@ -24,6 +26,8 @@ type FieldMapping struct {
 	DateFormat         *string `json:"date_format"`
 }
 
+// NewFieldMapping returns a FieldMapping with the
+// specified behavior.
 func NewFieldMapping(name, typ, analyzer string, store, index bool, includeTermVectors bool, includeInAll bool) *FieldMapping {
 	return &FieldMapping{
 		Name:               &name,
@@ -36,6 +40,7 @@ func NewFieldMapping(name, typ, analyzer string, store, index bool, includeTermV
 	}
 }
 
+// Options returns the indexing options for this field.
 func (fm *FieldMapping) Options() document.IndexingOptions {
 	var rv document.IndexingOptions
 	if *fm.Store {

diff --git a/mapping_index.go b/mapping_index.go
@@ -31,6 +31,13 @@ const defaultAnalyzer = "standard"
 const defaultDateTimeParser = "dateTimeOptional"
 const defaultByteArrayConverter = "json"
 
+// An IndexMapping controls how objects are place
+// into an index.
+// First the type of the object is deteremined.
+// Once the type is know, the appropriate/
+// DocumentMapping is selected by the type.
+// If no mapping was described for that type,
+// a DefaultMapping will be used.
 type IndexMapping struct {
 	TypeMapping           map[string]*DocumentMapping `json:"types,omitempty"`
 	DefaultMapping        *DocumentMapping            `json:"default_mapping"`

diff --git a/query.go b/query.go
@@ -15,6 +15,8 @@ import (
 	"github.com/blevesearch/bleve/search"
 )
 
+// A Query represents a description of the type
+// and parameters for a query into the index.
 type Query interface {
 	Boost() float64
 	SetBoost(b float64) Query
@@ -24,6 +26,8 @@ type Query interface {
 	Validate() error
 }
 
+// ParseQuery deserializes a JSON representation of
+// a Query object.
 func ParseQuery(input []byte) (Query, error) {
 	var tmp map[string]interface{}
 	err := json.Unmarshal(input, &tmp)

diff --git a/query_boolean.go b/query_boolean.go
@@ -23,6 +23,14 @@ type booleanQuery struct {
 	BoostVal float64 `json:"boost,omitempty"`
 }
 
+// NewBooleanQuery creates a compound Query composed
+// of several other Query objects.
+// Result documents must satisify ALL of the
+// must Queries.
+// Result documents must satsify NONE of the must not
+// Queries.
+// If there are any should queries, result documents
+// must satisfy at least one of them.
 func NewBooleanQuery(must []Query, should []Query, mustNot []Query) *booleanQuery {
 	min := 0.0
 	if len(should) > 0 {
@@ -31,6 +39,10 @@ func NewBooleanQuery(must []Query, should []Query, mustNot []Query) *booleanQuer
 	return NewBooleanQueryMinShould(must, should, mustNot, min)
 }
 
+// NewBooleanQueryMinShould is the same as
+// NewBooleanQuery, only it offers control of the
+// minimum number of should queries that must be
+// satisfied.
 func NewBooleanQueryMinShould(must []Query, should []Query, mustNot []Query, minShould float64) *booleanQuery {
 
 	rv := booleanQuery{

diff --git a/query_conjunction.go b/query_conjunction.go
@@ -20,6 +20,8 @@ type conjunctionQuery struct {
 	BoostVal  float64 `json:"boost,omitempty"`
 }
 
+// NewConjunctionQuery creates a new compound Query.
+// Result documents must satisfy all of the queries.
 func NewConjunctionQuery(conjuncts []Query) *conjunctionQuery {
 	return &conjunctionQuery{
 		Conjuncts: conjuncts,

diff --git a/query_date_range.go b/query_date_range.go
@@ -27,6 +27,10 @@ type dateRangeQuery struct {
 	DateTimeParser *string `json:"datetime_parser,omitempty"`
 }
 
+// NewDateRangeQuery creates a new Query for ranges
+// of date values.
+// A DateTimeParser is chosed based on the field.
+// Either, but not both endpoints can be nil.
 func NewDateRangeQuery(start, end *string) *dateRangeQuery {
 	return NewDateRangeInclusiveQuery(start, end, nil, nil)
 }

diff --git a/query_disjunction.go b/query_disjunction.go
@@ -21,17 +21,18 @@ type disjunctionQuery struct {
 	MinVal    float64 `json:"min"`
 }
 
+// NewDisjunctionQuery creates a new compound Query.
+// Result documents satisfy at least one Query.
 func NewDisjunctionQuery(disjuncts []Query) *disjunctionQuery {
 	return &disjunctionQuery{
 		Disjuncts: disjuncts,
 		BoostVal:  1.0,
 	}
 }
 
+// NewDisjunctionQueryMin creates a new compound Query.
+// Result documents satisfy at least min Queries.
 func NewDisjunctionQueryMin(disjuncts []Query, min float64) *disjunctionQuery {
-	if len(disjuncts) == 0 {
-		return nil
-	}
 	return &disjunctionQuery{
 		Disjuncts: disjuncts,
 		BoostVal:  1.0,

diff --git a/query_match.go b/query_match.go
@@ -22,6 +22,12 @@ type matchQuery struct {
 	BoostVal float64 `json:"boost,omitempty"`
 }
 
+// NewMatchQuery creates a Query for matching text.
+// An Analyzer is chosed based on the field.
+// Input text is analyzed using this analyzer.
+// Token terms resulting from this analysis are
+// used to perform term searches.  Result documents
+// must satisfy at least one of these term searches.
 func NewMatchQuery(match string) *matchQuery {
 	return &matchQuery{
 		Match:    match,

diff --git a/query_match_all.go b/query_match_all.go
@@ -17,6 +17,8 @@ type matchAllQuery struct {
 	BoostVal float64 `json:"boost,omitempty"`
 }
 
+// NewMatchAllQuery creates a Query which will
+// match all documents in the index.
 func NewMatchAllQuery() *matchAllQuery {
 	return &matchAllQuery{
 		BoostVal: 1.0,
-Original file line number
+Diff line change
@@ Expand Up / @@ -107,6 +107,7 @@ func newConfiguration() *configuration { @@
     	}
     }
+    // Config contains library level configuration
     var Config *configuration
     func init() {
@@ Expand Down @@