Omnibox: Improve Bookmarks Provider Comments

chrome/browser/autocomplete/bookmark_provider.cc

 // Copyright (c) 2012 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.
 
 #include "chrome/browser/autocomplete/bookmark_provider.h"
 
 #include <algorithm>
 #include <functional>
 #include <vector>
 
@@ skipping 170 matching lines @@
                                match.description.size());
   match.starred = true;
 
   // Summary on how a relevance score is determined for the match:
   //
   // For each term matching within the bookmark's title (as given by the set of
   // Snippet::MatchPositions) calculate a 'factor', sum up those factors, then
   // use the sum to figure out a value between the base score and the maximum
   // score.
   //
-  // The factor for each term is calculated based on:
+  // The factor for each term is the product of:
   //
   //  1) how much of the bookmark's title has been matched by the term:
   //       (term length / title length).
   //
   //  Example: Given a bookmark title 'abcde fghijklm', with a title length
   //     of 14, and two different search terms, 'abcde' and 'fghijklm', with
   //     term lengths of 5 and 8, respectively, 'fghijklm' will score higher
   //     (with a partial factor of 8/14 = 0.571) than 'abcde' (5/14 = 0.357).
   //
   //  2) where the term match occurs within the bookmark's title, giving more
   //     points for matches that appear earlier in the title:
   //       ((title length - position of match start) / title_length).
   //
   //  Example: Given a bookmark title of 'abcde fghijklm', with a title length
   //     of 14, and two different search terms, 'abcde' and 'fghij', with
   //     start positions of 0 and 6, respectively, 'abcde' will score higher
   //     (with a a partial factor of (14-0)/14 = 1.000 ) than 'fghij' (with
   //     a partial factor of (14-6)/14 = 0.571 ).
   //
-  // Once all term factors have been calculated they are summed. The resulting
-  // sum will never be greater than 1.0. This sum is then multiplied against
-  // the scoring range available, which is 299. The 299 is calculated by
-  // subtracting the minimum possible score, 900, from the maximum possible
-  // score, 1199. This product, ranging from 0 to 299, is added to the minimum
-  // possible score, 900, giving the preliminary score.
+  // Once all term factors have been calculated they are summed. The

[Peter Kasting, 2013/06/28 22:18:22]

How come you rewrapped this to have such shorter line lengths?

[Mark P, 2013/06/28 22:38:58]

Re-wrapped by hand.

+  // resulting sum will never be greater than 1.0 because of the way
+  // the bookmark model matches and removes overlaps.  (In particular,
+  // the bookmarks models only matches terms to the beginning of words

[Peter Kasting, 2013/06/28 22:18:22]

Nit: bookmarks models -> bookmark model

[Mark P, 2013/06/28 22:38:58]

Done.

+  // and it removes all overlapping matches, keeping only the longest.
+  // Together these mean that each character is included in at most
+  // one match.  This property ensures the sum of factors is at most 1.)
+  // This sum is then multiplied against the scoring range available,
+  // which is 299. The 299 is calculated by subtracting the minimum
+  // possible score, 900, from the maximum possible score, 1199. This
+  // product, ranging from 0 to 299, is added to the minimum possible
+  // score, 900, giving the preliminary score.
   //
   // If the preliminary score is less than the maximum possible score, 1199,
   // it can be boosted up to that maximum possible score if the URL referenced
   // by the bookmark is also referenced by any of the user's other bookmarks.
   // A count of how many times the bookmark's URL is referenced is determined
   // and, for each additional reference beyond the one for the bookmark being
   // scored up to a maximum of three, the score is boosted by a fixed amount
   // given by |kURLCountBoost|, below.
   //
   ScoringFunctor position_functor =
@@ skipping 37 matching lines @@
   for (Snippet::MatchPositions::const_iterator i = positions.begin();
        i != positions.end(); ++i) {
     AutocompleteMatch::ACMatchClassifications new_class;
     AutocompleteMatch::ClassifyLocationInString(i->first, i->second - i->first,
         text_length, 0, &new_class);
     classifications = AutocompleteMatch::MergeClassifications(
         classifications, new_class);
   }
   return classifications;
 }