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
+  // sum will never be greater than 1.0 because of the way the bookmark model
+  // matches and removes overlaps. (In particular, the bookmark model only
+  // matches terms to the beginning of words 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

[Peter Kasting, 2013/06/28 22:44:14]

Super nit: "sum" will fit on the previous line, which will result in
chain-rewrapping the subsequent lines.

[Mark P, 2013/06/28 22:55:05]

It looks ugly like that because the line above is comparably short.

[Peter Kasting, 2013/06/28 22:57:17]

We are wrapping our lines based on aesthetics of making them similar lengths??

+  // 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
@@ skipping 40 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;
 }