Updates SpellcheckWordIterator::GetNextWord to return an enum.

chrome/renderer/spellchecker/spellcheck_worditerator.h

 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Defines an iterator class that enumerates words supported by our spellchecker
 // from multi-language text. This class is used for filtering out characters
 // not supported by our spellchecker.
 
 #ifndef CHROME_RENDERER_SPELLCHECKER_SPELLCHECK_WORDITERATOR_H_
 #define CHROME_RENDERER_SPELLCHECKER_SPELLCHECK_WORDITERATOR_H_
@@ skipping 94 matching lines @@
 //
 //   base::string16 word;
 //   int offset;
 //   int length;
 //   while (iterator.GetNextWord(&word, &offset, &length)) {
 //     ...
 //   }
 //
 class SpellcheckWordIterator {
  public:
+  enum WordIteratorStatus {
+    // The end of a sequence of text that the iterator recognizes as characters
+    // that can form a word.
+    IS_WORD,
+    // Non-word characters that the iterator can skip past, such as punctuation,
+    // whitespace, and characters from another character set.
+    IS_SKIPPABLE_CHAR,

[please use gerrit instead, 2015/08/11 22:54:10]

IS_SKIPPABLE

Putting "_CHAR" in there might confuse people into thinking that only a single
character was encountered. Although the implementation might behave this way,
let's not expose too much implementation details in the API for the next layer
up the stack.

[Julius, 2015/08/12 20:25:59]

Done.

+    // The end of the text that the iterator is going over.
+    IS_END_OF_TEXT
+  };
+
   SpellcheckWordIterator();
   ~SpellcheckWordIterator();
 
   // Initializes a word-iterator object with the language-specific attribute. If
   // we need to split contractions and concatenated words, call this function
   // with its 'allow_contraction' parameter false. (This function uses lots of
   // temporal memory to compile a custom word-break rule into an automaton.)
   bool Initialize(const SpellcheckCharAttribute* attribute,
                   bool allow_contraction);
 
   // Returns whether this word iterator is initialized.
   bool IsInitialized() const;
 
   // Set text to be iterated. (This text does not have to be NULL-terminated.)
   // This function also resets internal state so we can reuse this iterator
   // without calling Initialize().
   bool SetText(const base::char16* text, size_t length);
 
-  // Retrieves a word (or a contraction), stores its copy to 'word_string', and
-  // stores the position and the length for input word to 'word_start'. Since
-  // this function normalizes the output word, the length of 'word_string' may
-  // be different from the 'word_length'. Therefore, when we call functions that
-  // changes the input text, such as string16::replace(), we need to use
-  // 'word_start' and 'word_length' as listed in the following snippet.
-  //
-  //   while(iterator.GetNextWord(&word, &offset, &length))

[please use gerrit instead, 2015/08/11 22:54:10]

Keep this example in the comment please.

[Julius, 2015/08/12 20:25:59]

Done.

-  //     text.replace(offset, length, word);
-  //
-  bool GetNextWord(base::string16* word_string,
-                   int* word_start,
-                   int* word_length);
+  // Advances |iterator_| through |text_| and gets the current status of the
+  // word iterator within the |text|:
+  //  - Returns IS_WORD if the iterator just found the end of a sequence of word

[please use gerrit instead, 2015/08/11 22:54:10]

Put a newline before a bullet point to make the comment easier to read.

[Julius, 2015/08/12 20:25:59]

Done.

+  //    characters and it was able to normalize the sequence. This stores the
+  //    normalized string into |word_string| and stores the position and length
+  //    into |word_start| and |word_length| respectively. Keep in mind that
+  //    since this function normalizes the output word, the length of
+  //    |word_string| may be different from the |word_length|.
+  //  - Returns IS_SKIPPABLE_CHAR if the iterator just found a character that
+  //    the iterator can skip past such as punctuation, whitespace, and
+  //    characters from another character set.
+  //  - Returns IS_END_OF_TEXT if the iterator has reached the end of |text_|.
+  SpellcheckWordIterator::WordIteratorStatus
+  GetNextWord(base::string16* word_string, int* word_start, int* word_length);
 
   // Releases all the resources attached to this object.
   void Reset();
 
  private:
   // Normalizes a non-terminated string returned from an ICU word-break
   // iterator. A word returned from an ICU break iterator may include characters
   // not supported by our spellchecker, e.g. ligatures, combining/ characters,
   // full-width letters, etc. This function replaces such characters with
   // alternative characters supported by our spellchecker. This function also
@@ skipping 11 matching lines @@
   const SpellcheckCharAttribute* attribute_;
 
   // The break iterator.
   scoped_ptr<base::i18n::BreakIterator> iterator_;
 
   DISALLOW_COPY_AND_ASSIGN(SpellcheckWordIterator);
 };
 
 #endif  // CHROME_RENDERER_SPELLCHECKER_SPELLCHECK_WORDITERATOR_H_