improve go docs at the top level

part of #79

config.go

@@ -107,6 +107,7 @@ func newConfiguration() *configuration {
 	}
 }
 
+// Config contains library level configuration
 var Config *configuration
 
 func init() {

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)
 }

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,6 +435,21 @@ func (i *indexImpl) Search(req *SearchRequest) (*SearchResult, error) {
 	}, nil
 }
 
+// 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, ERROR_INDEX_CLOSED
+	}
+	return i.i.Fields()
+}
+
+// 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()
@@ -427,16 +461,10 @@ func (i *indexImpl) DumpAll() chan interface{} {
 	return i.i.DumpAll()
 }
 
-func (i *indexImpl) Fields() ([]string, error) {
-	i.mutex.RLock()
-	defer i.mutex.RUnlock()
-
-	if !i.open {
-		return nil, ERROR_INDEX_CLOSED
-	}
-	return i.i.Fields()
-}
-
+// 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()

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,6 +88,8 @@ 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,
@@ -82,16 +97,23 @@ func NewDocumentMapping() *DocumentMapping {
 	}
 }
 
+// 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"`

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 {

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"`

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)

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{

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,

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)
 }

query_disjunction.go

@@ -21,6 +21,8 @@ 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,
@@ -28,10 +30,9 @@ func NewDisjunctionQuery(disjuncts []Query) *disjunctionQuery {
 	}
 }
 
+// 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,

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,

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,

query_match_none.go

@@ -17,6 +17,8 @@ type matchNoneQuery struct {
 	BoostVal float64 `json:"boost,omitempty"`
 }
 
+// NewMatchNoneQuery creates a Query which will not
+// match any documents in the index.
 func NewMatchNoneQuery() *matchNoneQuery {
 	return &matchNoneQuery{
 		BoostVal: 1.0,

query_match_phrase.go

@@ -22,6 +22,13 @@ type matchPhraseQuery struct {
 	BoostVal    float64 `json:"boost,omitempty"`
 }
 
+// NewMatchPhraseQuery creates a new Query object
+// for matching phrases in the index.
+// An Analyzer is chosed based on the field.
+// Input text is analyzed using this analyzer.
+// Token terms resulting from this analysis are
+// used to build a search phrase.  Result documents
+// must match this phrase.
 func NewMatchPhraseQuery(matchPhrase string) *matchPhraseQuery {
 	return &matchPhraseQuery{
 		MatchPhrase: matchPhrase,

query_numeric_range.go

@@ -22,10 +22,19 @@ type numericRangeQuery struct {
 	BoostVal     float64  `json:"boost,omitempty"`
 }
 
+// NewNumericRangeQuery creates a new Query for ranges
+// of date values.
+// Either, but not both endpoints can be nil.
+// The minimum value is inclusive.
+// The maximum value is exclusive.
 func NewNumericRangeQuery(min, max *float64) *numericRangeQuery {
 	return NewNumericRangeInclusiveQuery(min, max, nil, nil)
 }
 
+// NewNumericRangeQuery creates a new Query for ranges
+// of date values.
+// Either, but not both endpoints can be nil.
+// Control endpoint inclusion with inclusiveMin, inclusiveMax.
 func NewNumericRangeInclusiveQuery(min, max *float64, minInclusive, maxInclusive *bool) *numericRangeQuery {
 	return &numericRangeQuery{
 		Min:          min,

query_phrase.go

@@ -21,6 +21,11 @@ type phraseQuery struct {
 	BoostVal float64 `json:"boost,omitempty"`
 }
 
+// NewPhraseQuery creates a new Query for finding
+// exact term phrases in the index.
+// The provided terms must exist in the correct
+// order, at the correct index offsets, in the
+// specified field.
 func NewPhraseQuery(terms []string, field string) *phraseQuery {
 	termQueries := make([]Query, len(terms))
 	for i, term := range terms {

query_prefix.go

@@ -19,6 +19,9 @@ type prefixQuery struct {
 	BoostVal float64 `json:"boost,omitempty"`
 }
 
+// NewPrefixQuery creates a new Query which finds
+// documents containing terms that start with the
+// specified prefix.
 func NewPrefixQuery(prefix string) *prefixQuery {
 	return &prefixQuery{
 		Prefix:   prefix,

query_string.go

@@ -18,6 +18,9 @@ type queryStringQuery struct {
 	BoostVal float64 `json:"boost,omitempty"`
 }
 
+// NewQueryStringQuery creates a new Query used for
+// finding documents that satisfy a query string.  The
+// query string is a small query language for humans.
 func NewQueryStringQuery(query string) *queryStringQuery {
 	return &queryStringQuery{
 		Query:    query,

query_term.go

@@ -19,6 +19,8 @@ type termQuery struct {
 	BoostVal float64 `json:"boost,omitempty"`
 }
 
+// NewTermQuery creates a new Query for finding an
+// exact term match in the index.
 func NewTermQuery(term string) *termQuery {
 	return &termQuery{
 		Term:     term,

search.go

@@ -70,6 +70,9 @@ func (dr *dateTimeRange) UnmarshalJSON(input []byte) error {
 	return nil
 }
 
+// A FacetRequest describes an facet or aggregation
+// of the result document set you would like to be
+// built.
 type FacetRequest struct {
 	Size           int
 	Field          string
@@ -77,6 +80,9 @@ type FacetRequest struct {
 	DateTimeRanges []*dateTimeRange `json:"date_ranges,omitempty"`
 }
 
+// NewFacetRequest creates a facet on the specified
+// field that limits the number of entries to the
+// specified size.
 func NewFacetRequest(field string, size int) *FacetRequest {
 	return &FacetRequest{
 		Field: field,
@@ -84,6 +90,10 @@ func NewFacetRequest(field string, size int) *FacetRequest {
 	}
 }
 
+// AddDateTimeRange adds a bucket to a field
+// containing date values.  Documents with a
+// date value falling into this range are tabulated
+// as part of this bucket/range.
 func (fr *FacetRequest) AddDateTimeRange(name string, start, end time.Time) {
 	if fr.DateTimeRanges == nil {
 		fr.DateTimeRanges = make([]*dateTimeRange, 0, 1)
@@ -91,6 +101,10 @@ func (fr *FacetRequest) AddDateTimeRange(name string, start, end time.Time) {
 	fr.DateTimeRanges = append(fr.DateTimeRanges, &dateTimeRange{Name: name, Start: start, End: end})
 }
 
+// AddNumericRange adds a bucket to a field
+// containing numeric values.  Documents with a
+// numeric value falling into this range are
+// tabulated as part of this bucket/range.
 func (fr *FacetRequest) AddNumericRange(name string, min, max *float64) {
 	if fr.NumericRanges == nil {
 		fr.NumericRanges = make([]*numericRange, 0, 1)
@@ -98,23 +112,43 @@ func (fr *FacetRequest) AddNumericRange(name string, min, max *float64) {
 	fr.NumericRanges = append(fr.NumericRanges, &numericRange{Name: name, Min: min, Max: max})
 }
 
+// FacetsRequests groups together all the
+// FacetRequest objects for a single query.
 type FacetsRequest map[string]*FacetRequest
 
+// HighlighRequest describes how field matches
+// should be highlighted.
 type HighlightRequest struct {
 	Style  *string  `json:"style"`
 	Fields []string `json:"fields"`
 }
 
+// NewHighlight creates a default
+// HighlightRequest.
 func NewHighlight() *HighlightRequest {
 	return &HighlightRequest{}
 }
 
+// NewHighlightWithStyle creates a HighlightRequest
+// with an alternate style.
 func NewHighlightWithStyle(style string) *HighlightRequest {
 	return &HighlightRequest{
 		Style: &style,
 	}
 }
 
+// A SearchRequest describes all the parameters
+// needed to search the index.
+// Query is required.
+// Size/From describe how much and which part of the
+// result set to return.
+// Highlight describes optional search result
+// highlighting.
+// Fields desribed a list of field values whcih
+// should be retrieved for result documents.
+// Facets describe the set of facets to be computed.
+// Explain triggers inclusion of additional search
+// result score explanations.
 type SearchRequest struct {
 	Query     Query             `json:"query"`
 	Size      int               `json:"size"`
@@ -125,6 +159,7 @@ type SearchRequest struct {
 	Explain   bool              `json:"explain"`
 }
 
+// AddFacet adds a FacetRequest to this SearchRequest
 func (r *SearchRequest) AddFacet(facetName string, f *FacetRequest) {
 	if r.Facets == nil {
 		r.Facets = make(FacetsRequest, 1)
@@ -132,6 +167,8 @@ func (r *SearchRequest) AddFacet(facetName string, f *FacetRequest) {
 	r.Facets[facetName] = f
 }
 
+// UnmarshalJSON deserializes a JSON representation of
+// a SearchRequest
 func (r *SearchRequest) UnmarshalJSON(input []byte) error {
 	var temp struct {
 		Q         json.RawMessage   `json:"query"`
@@ -170,10 +207,16 @@ func (r *SearchRequest) UnmarshalJSON(input []byte) error {
 
 }
 
+// NewSearchRequest creates a new SearchRequest
+// for the Query, using default values for all
+// other search parameters.
 func NewSearchRequest(q Query) *SearchRequest {
 	return NewSearchRequestOptions(q, 10, 0, false)
 }
 
+// NewSearchRequestOptions creates a new SearchRequest
+// for the Query, with the requested size, from
+// and explanation search parameters.
 func NewSearchRequestOptions(q Query, size, from int, explain bool) *SearchRequest {
 	return &SearchRequest{
 		Query:   q,
@@ -183,6 +226,8 @@ func NewSearchRequestOptions(q Query, size, from int, explain bool) *SearchReque
 	}
 }
 
+// A SearchResult describes the results of executing
+// a SearchRequest.
 type SearchResult struct {
 	Request  *SearchRequest                 `json:"request"`
 	Hits     search.DocumentMatchCollection `json:"hits"`