code review 3699041: godoc: support for regular expression full text search

src/cmd/godoc/index.go

 // Copyright 2009 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 // This file contains the infrastructure to create an
 // identifier and full-text index for a set of Go files.
 //
 // Algorithm for identifier index:
 // - traverse all .go files of the file tree specified by root
-// - for each word (identifier) encountered, collect all occurences (spots)
+// - for each word (identifier) encountered, collect all occurrences (spots)
 //   into a list; this produces a list of spots for each word
 // - reduce the lists: from a list of spots to a list of FileRuns,
 //   and from a list of FileRuns into a list of PakRuns
 // - make a HitList from the PakRuns
 //
 // Details:
 // - keep two lists per word: one containing package-level declarations
 //   that have snippets, and one containing all other spots
 // - keep the snippets in a separate table indexed by snippet index
 //   and store the snippet index in place of the line number in a SpotInfo
@@ skipping 220 matching lines @@
 }
 
 
 // A File describes a Go file.
 type File struct {
         Path string // complete file name
         Pak  Pak    // the package to which the file belongs
 }
 
 
-// A Spot describes a single occurence of a word.
+// A Spot describes a single occurrence of a word.
 type Spot struct {
         File *File
         Info SpotInfo
 }
 
 
 // A FileRun is a list of KindRuns belonging to the same file.
 type FileRun struct {
         File   *File
         Groups []*KindRun
@@ skipping 167 matching lines @@
 // ----------------------------------------------------------------------------
 // Indexer
 
 // Adjust these flags as seems best.
 const excludeMainPackages = false
 const excludeTestFiles = false
 
 
 type IndexResult struct {
         Decls  RunList // package-level declarations (with snippets)
-        Others RunList // all other occurences
+        Others RunList // all other occurrences
 }
 
 
 // Statistics provides statistics information for an index.
 type Statistics struct {
         Bytes int // total size of indexed source files
         Files int // number of indexed source files
         Lines int // number of lines (all files)
         Words int // number of different identifiers
-        Spots int // number of identifier occurences
+        Spots int // number of identifier occurrences
 }
 
 
 // An Indexer maintains the data structures and provides the machinery
 // for indexing .go files under a file tree. It implements the path.Visitor
 // interface for walking file trees, and the ast.Visitor interface for
 // walking Go ASTs.
 type Indexer struct {
         fset     *token.FileSet          // file set for all indexed files
         sources  bytes.Buffer            // concatenated sources
@@ skipping 243 matching lines @@
         x.stats.Files++
         x.stats.Lines += x.current.LineCount()
 }
 
 
 // ----------------------------------------------------------------------------
 // Index
 
 type LookupResult struct {
         Decls  HitList // package-level declarations (with snippets)
-        Others HitList // all other occurences
+        Others HitList // all other occurrences
 }
 
 
 type Index struct {
         fset     *token.FileSet           // file set used during indexing; nil if no textindex
         suffixes *suffixarray.Index       // suffixes for concatenated sources; nil if no textindex
         words    map[string]*LookupResult // maps words to hit lists
         alts     map[string]*AltWords     // maps canonical(words) to lists of alternative spellings
         snippets []*Snippet               // all snippets, indexed by snippet index
         stats    Statistics
@@ skipping 179 matching lines @@
 }
 
 
 // A FileLines value specifies a file and line numbers within that file.
 type FileLines struct {
         Filename string
         Lines    []int
 }
 
 
-// LookupRegexp returns the number and list of matches where a regular
+// LookupRegexp returns the number of matches and the matches where a regular
 // expression r is found in the full text index. At most n matches are
 // returned (thus found <= n).
 //
 func (x *Index) LookupRegexp(r *regexp.Regexp, n int) (found int, result []FileLines) {
         if x.suffixes == nil || n <= 0 {
                 return
         }
         // n > 0
 
         var list positionList
-        // FindAllIndex returns matches that may span across file boundaries.
-        // This is unlikely, buf after eliminating them we may end up with
-        // fewer than n matches. If we don't have enough at the end, redo
+        // FindAllIndex may returns matches that span across file boundaries.
+        // Such matches are unlikely, buf after eliminating them we may end up
+        // with fewer than n matches. If we don't have enough at the end, redo
         // the search with an increased value n1, but only if FindAllIndex
         // returned all the requested matches in the first place (if it
-        // returned fewer than that then there cannot be more).
+        // returned fewer than that there cannot be more).
         for n1 := n; found < n; n1 += n - found {
                 found = 0
                 matches := x.suffixes.FindAllIndex(r, n1)
                 // compute files, exclude matches that span file boundaries,
                 // and map offsets to file-local offsets
                 list = make(positionList, len(matches))
                 for _, m := range matches {
                         // by construction, an offset corresponds to the Pos value
                         // for the file set - use it to get the file and line
                         p := token.Pos(m[0])
@@ skipping 28 matching lines @@
                 if m.filename != last {
                         addLines()
                         last = m.filename
                 }
                 lines = append(lines, m.line)
         }
         addLines()
 
         return
 }