documentations (#124)

Author: AvitalFineRedis

redisearch/aggregate.go

@@ -7,7 +7,12 @@ import (
 	"reflect"
 )
 
-// Projection
+// Projection - Apply a 1-to-1 transformation on one or more properties,
+// and either store the result as a new property down the pipeline, or
+// replace any property using this transformation. Expression is an expression
+// that can be used to perform arithmetic operations on numeric properties,
+// or functions that can be applied on properties depending on their types,
+// or any combination thereof.
 type Projection struct {
 	Expression string
 	Alias      string
@@ -66,13 +71,16 @@ func (c Cursor) Serialize() redis.Args {
 	return args
 }
 
-// GroupBy
+//GroupBy groups the results in the pipeline based on one or more properties.
+//Each group should have at least one reducer, a function that handles the group
+//entries, either counting them, or performing multiple aggregate operations.
 type GroupBy struct {
 	Fields   []string
 	Reducers []Reducer
 	Paging   *Paging
 }
 
+// NewGroupBy creates a new GroupBy object
 func NewGroupBy() *GroupBy {
 	return &GroupBy{
 		Fields:   make([]string, 0),
@@ -81,6 +89,7 @@ func NewGroupBy() *GroupBy {
 	}
 }
 
+// AddFields to the group. Can be single string or list of strings.
 func (g *GroupBy) AddFields(fields interface{}) *GroupBy {
 	switch fields.(type) {
 	case string:
@@ -93,11 +102,13 @@ func (g *GroupBy) AddFields(fields interface{}) *GroupBy {
 	return g
 }
 
+// Reduce adds reducer to the group's list
 func (g *GroupBy) Reduce(reducer Reducer) *GroupBy {
 	g.Reducers = append(g.Reducers, reducer)
 	return g
 }
 
+// Limit adds Paging to the GroupBy object
 func (g *GroupBy) Limit(offset int, num int) *GroupBy {
 	g.Paging = NewPaging(offset, num)
 	return g
@@ -140,6 +151,7 @@ func NewAggregateQuery() *AggregateQuery {
 	}
 }
 
+// SetQuery sets the query to the AggregateQuery
 func (a *AggregateQuery) SetQuery(query *Query) *AggregateQuery {
 	a.Query = query
 	return a
@@ -150,11 +162,14 @@ func (a *AggregateQuery) SetWithSchema(value bool) *AggregateQuery {
 	return a
 }
 
+// SetVerbatim - If set, we do not try to use stemming for query expansion but search
+// the query terms verbatim.
 func (a *AggregateQuery) SetVerbatim(value bool) *AggregateQuery {
 	a.Verbatim = value
 	return a
 }
 
+// SetMax is used to optimized sorting, by sorting only for the n-largest elements
 func (a *AggregateQuery) SetMax(value int) *AggregateQuery {
 	a.Max = value
 	return a
@@ -174,13 +189,13 @@ func (a *AggregateQuery) CursorHasResults() (res bool) {
 	return
 }
 
-//Adds a APPLY clause to the aggregate plan
+//Apply a 1-to-1 transformation on some property
 func (a *AggregateQuery) Apply(expression Projection) *AggregateQuery {
 	a.AggregatePlan = a.AggregatePlan.AddFlat(expression.Serialize())
 	return a
 }
 
-//Sets the limit for the initial pool of results from the query.
+//Limit the number of results to return just num results starting at index offset (zero-based).
 func (a *AggregateQuery) Limit(offset int, num int) *AggregateQuery {
 	a.Paging = NewPaging(offset, num)
 	return a
@@ -219,7 +234,8 @@ func (a *AggregateQuery) SortBy(SortByProperties []SortingKey) *AggregateQuery {
 	return a
 }
 
-//Specify filters to filter the results using predicates relating to values in the result set.
+//Filter the results using predicate expressions relating to values in each result.
+//They are is applied post-query and relate to the current state of the pipeline.
 func (a *AggregateQuery) Filter(expression string) *AggregateQuery {
 	a.AggregatePlan = a.AggregatePlan.Add("FILTER", expression)
 	//a.Filters = append(a.Filters, expression)
@@ -241,7 +257,6 @@ func (q AggregateQuery) Serialize() redis.Args {
 	if q.Verbatim {
 		args = args.Add("VERBATIM")
 	}
-
 	// WITHCURSOR
 	if q.WithCursor {
 		args = args.AddFlat(q.Cursor.Serialize())

redisearch/autocomplete.go

@@ -68,7 +68,7 @@ func (a *Autocompleter) AddTerms(terms ...Suggestion) error {
 	return nil
 }
 
-// AddTerms pushes new term suggestions to the index
+// DeleteTerms deletes term suggestions from the index
 func (a *Autocompleter) DeleteTerms(terms ...Suggestion) error {
 	conn := a.pool.Get()
 	defer conn.Close()
@@ -94,7 +94,7 @@ func (a *Autocompleter) DeleteTerms(terms ...Suggestion) error {
 	return nil
 }
 
-// AddTerms pushes new term suggestions to the index
+// Length gets the size of the suggestion
 func (a *Autocompleter) Length() (len int64, err error) {
 	conn := a.pool.Get()
 	defer conn.Close()
@@ -128,8 +128,8 @@ func (a *Autocompleter) Suggest(prefix string, num int, fuzzy bool) (ret []Sugge
 
 // SuggestOpts gets completion suggestions from the Autocompleter dictionary to the given prefix.
 // SuggestOptions are passed allowing you specify if the returned values contain a payload, and scores.
-// If SuggestOptions.Fuzzy is set, we also complete for prefixes that are in 1 Levenshtein distance from the
-// given prefix
+// If SuggestOptions.Fuzzy is set, we also complete for prefixes that are in 1 Levenshtein distance
+// from the given prefix
 func (a *Autocompleter) SuggestOpts(prefix string, opts SuggestOptions) (ret []Suggestion, err error) {
 	conn := a.pool.Get()
 	defer conn.Close()

redisearch/client.go

@@ -126,12 +126,10 @@ func (i *Client) Search(q *Query) (docs []Document, total int, err error) {
 		payloadIdx = skip
 		skip++
 	}
-
 	if q.Flags&QueryNoContent == 0 {
 		fieldsIdx = skip
 		skip++
 	}
-
 	if len(res) > skip {
 		for i := 1; i < len(res); i += skip {
 
@@ -145,7 +143,8 @@ func (i *Client) Search(q *Query) (docs []Document, total int, err error) {
 	return
 }
 
-// Adds an alias to an index.
+// AliasAdd adds an alias to an index.
+// Indexes can have more than one alias, though an alias cannot refer to another alias.
 func (i *Client) AliasAdd(name string) (err error) {
 	conn := i.pool.Get()
 	defer conn.Close()
@@ -154,7 +153,7 @@ func (i *Client) AliasAdd(name string) (err error) {
 	return
 }
 
-// Deletes an alias to an index.
+// AliasDel deletes an alias from index.
 func (i *Client) AliasDel(name string) (err error) {
 	conn := i.pool.Get()
 	defer conn.Close()
@@ -163,7 +162,9 @@ func (i *Client) AliasDel(name string) (err error) {
 	return
 }
 
-// Deletes an alias to an index.
+// AliasUpdate differs from the AliasAdd in that it will remove the alias association with
+// a previous index, if any. AliasAdd will fail, on the other hand, if the alias is already
+// associated with another index.
 func (i *Client) AliasUpdate(name string) (err error) {
 	conn := i.pool.Get()
 	defer conn.Close()
@@ -172,7 +173,7 @@ func (i *Client) AliasUpdate(name string) (err error) {
 	return
 }
 
-// Adds terms to a dictionary.
+// DictAdd adds terms to a dictionary.
 func (i *Client) DictAdd(dictionaryName string, terms []string) (newTerms int, err error) {
 	conn := i.pool.Get()
 	defer conn.Close()
@@ -182,7 +183,7 @@ func (i *Client) DictAdd(dictionaryName string, terms []string) (newTerms int, e
 	return
 }
 
-// Deletes terms from a dictionary
+// DictDel deletes terms from a dictionary
 func (i *Client) DictDel(dictionaryName string, terms []string) (deletedTerms int, err error) {
 	conn := i.pool.Get()
 	defer conn.Close()
@@ -192,7 +193,7 @@ func (i *Client) DictDel(dictionaryName string, terms []string) (deletedTerms in
 	return
 }
 
-// Dumps all terms in the given dictionary.
+// DictDump dumps all terms in the given dictionary.
 func (i *Client) DictDump(dictionaryName string) (terms []string, err error) {
 	conn := i.pool.Get()
 	defer conn.Close()
@@ -336,14 +337,12 @@ func (i *Client) MultiGet(documentIds []string) (docs []*Document, err error) {
 			} else {
 				docs[i] = nil
 			}
-
 		}
-
 	}
 	return
 }
 
-// Explain Return a textual string explaining the query
+// Explain Return a textual string explaining the query (execution plan)
 func (i *Client) Explain(q *Query) (string, error) {
 	conn := i.pool.Get()
 	defer conn.Close()
@@ -354,22 +353,21 @@ func (i *Client) Explain(q *Query) (string, error) {
 	return redis.String(conn.Do("FT.EXPLAIN", args...))
 }
 
-//  Deletes the index and all the keys associated with it.
+// Drop deletes the index and all the keys associated with it.
 func (i *Client) Drop() error {
 	conn := i.pool.Get()
 	defer conn.Close()
 
 	_, err := conn.Do("FT.DROP", i.name)
 	return err
-
 }
 
 // Deletes the secondary index and optionally the associated hashes
 //
 // Available since RediSearch 2.0.
 //
-// By default, DropIndex() which is a wrapper for RediSearch FT.DROPINDEX does not delete the document hashes associated with the index.
-// Setting the argument deleteDocuments to true deletes the hashes as well.
+// By default, DropIndex() which is a wrapper for RediSearch FT.DROPINDEX does not delete the document
+// hashes associated with the index. Setting the argument deleteDocuments to true deletes the hashes as well.
 func (i *Client) DropIndex(deleteDocuments bool) error {
 	conn := i.pool.Get()
 	defer conn.Close()
@@ -389,7 +387,7 @@ func (i *Client) Delete(docId string, deleteDocument bool) (err error) {
 	return i.delDoc(docId, deleteDocument)
 }
 
-// Delete the document from the index and also delete the HASH key in which the document is stored
+// DeleteDocument delete the document from the index and also delete the HASH key in which the document is stored
 func (i *Client) DeleteDocument(docId string) (err error) {
 	return i.delDoc(docId, true)
 }
@@ -406,6 +404,7 @@ func (i *Client) delDoc(docId string, deleteDocument bool) (err error) {
 	return
 }
 
+// Internal method to be used by Info()
 func (info *IndexInfo) setTarget(key string, value interface{}) error {
 	v := reflect.ValueOf(info).Elem()
 	for i := 0; i < v.NumField(); i++ {
@@ -602,8 +601,8 @@ func (i *Client) GetTagVals(index string, filedName string) ([]string, error) {
 	return redis.Strings(conn.Do("FT.TAGVALS", args...))
 }
 
-// Adds a synonym group.
-// Deprecated: This function  is not longer supported on RediSearch 2.0 and above, use SynUpdate instead
+// SynAdd adds a synonym group.
+// Deprecated: This function is not longer supported on RediSearch 2.0 and above, use SynUpdate instead
 func (i *Client) SynAdd(indexName string, terms []string) (int64, error) {
 	conn := i.pool.Get()
 	defer conn.Close()
@@ -612,7 +611,7 @@ func (i *Client) SynAdd(indexName string, terms []string) (int64, error) {
 	return redis.Int64(conn.Do("FT.SYNADD", args...))
 }
 
-// Updates a synonym group, with additional terms.
+// SynUpdate updates a synonym group, with additional terms.
 func (i *Client) SynUpdate(indexName string, synonymGroupId int64, terms []string) (string, error) {
 	conn := i.pool.Get()
 	defer conn.Close()
@@ -621,7 +620,7 @@ func (i *Client) SynUpdate(indexName string, synonymGroupId int64, terms []strin
 	return redis.String(conn.Do("FT.SYNUPDATE", args...))
 }
 
-// Dumps the contents of a synonym group.
+// SynDump dumps the contents of a synonym group.
 func (i *Client) SynDump(indexName string) (map[string][]int64, error) {
 	conn := i.pool.Get()
 	defer conn.Close()
@@ -650,7 +649,7 @@ func (i *Client) SynDump(indexName string) (map[string][]int64, error) {
 }
 
 // Adds a document to the index from an existing HASH key in Redis.
-// Deprecated: This function  is not longer supported on RediSearch 2.0 and above, use HSET instead
+// Deprecated: This function is not longer supported on RediSearch 2.0 and above, use HSET instead
 // See the example ExampleClient_CreateIndexWithIndexDefinition for a deeper understanding on how to move towards using hashes on your application
 func (i *Client) AddHash(docId string, score float32, language string, replace bool) (string, error) {
 	conn := i.pool.Get()

redisearch/document.go

@@ -86,7 +86,8 @@ func EscapeTextFileString(value string) string {
 	return value
 }
 
-// convert the result from a redis query to a proper Document object
+// internal function
+// loadDocument convert the result from a redis query to a proper Document object
 func loadDocument(arr []interface{}, idIdx, scoreIdx, payloadIdx, fieldsIdx int) (Document, error) {
 
 	var score float64 = 1
@@ -111,7 +112,8 @@ func loadDocument(arr []interface{}, idIdx, scoreIdx, payloadIdx, fieldsIdx int)
 	return doc, nil
 }
 
-// SetPayload Sets the document payload
+// internal function used by loadDocument()
+// loadFields loads the fields of the document
 func (d *Document) loadFields(lst []interface{}) *Document {
 	for i := 0; i < len(lst); i += 2 {
 		var prop string
@@ -137,7 +139,10 @@ func (d *Document) loadFields(lst []interface{}) *Document {
 // DocumentList is used to sort documents by descending score
 type DocumentList []Document
 
-func (l DocumentList) Len() int           { return len(l) }
+// Len returns the length of the DocumentList
+func (l DocumentList) Len() int { return len(l) }
+
+// Swap two documents in the list by their index
 func (l DocumentList) Swap(i, j int)      { l[i], l[j] = l[j], l[i] }
 func (l DocumentList) Less(i, j int) bool { return l[i].Score > l[j].Score } //reverse sorting
 

redisearch/index.go

@@ -12,6 +12,7 @@ const (
 	JSON
 )
 
+// Parse IndexType enum to string
 func (it IndexType) String() string {
 	return [...]string{"HASH", "JSON"}[it]
 }

redisearch/query.go

@@ -73,7 +73,7 @@ type SummaryOptions struct {
 	Separator    string // default "..."
 }
 
-// Query is a single search query and all its parameters and predicates
+// Query is a single search query containing all its parameters and predicates
 type Query struct {
 	Raw string
 
@@ -243,7 +243,7 @@ func appendNumArgs(num float64, exclude bool, args redis.Args) redis.Args {
 	return append(args, num)
 }
 
-// AddFilter adds a filter to the query
+// AddFilter adds a filter to the query.
 func (q *Query) AddFilter(f Filter) *Query {
 	if q.Filters == nil {
 		q.Filters = []Filter{}

redisearch/spellcheck.go

@@ -93,7 +93,10 @@ func NewMisspelledTerm(term string) MisspelledTerm {
 	}
 }
 
+// Len returns the length of the MisspelledSuggestionList
 func (l MisspelledTerm) Len() int { return len(l.MisspelledSuggestionList) }
+
+// Swap two suggestions in the list
 func (l MisspelledTerm) Swap(i, j int) {
 	maxLen := len(l.MisspelledSuggestionList)
 	if i < maxLen && j < maxLen {