Fix RegisterChromeBrowser definition and usage in shell_util

chrome/installer/util/shell_util.h

Index: chrome/installer/util/shell_util.h
diff --git a/chrome/installer/util/shell_util.h b/chrome/installer/util/shell_util.h
index 85e5fbd7d0f9e8123a5e2b2157810f3ad4ede95f..27a450e3deae762813b09973a31762584079f3ab 100644
--- a/chrome/installer/util/shell_util.h
+++ b/chrome/installer/util/shell_util.h
@@ -244,27 +244,36 @@ class ShellUtil {
                                               const string16& chrome_exe,
                                               const string16& protocol);
 
-  // This method adds Chrome to the list that shows up in Add/Remove Programs->
-  // Set Program Access and Defaults and also creates Chrome ProgIds under
-  // Software\Classes. This method requires write access to HKLM so is just
-  // best effort deal. If write to HKLM fails and elevate_if_not_admin is true,
-  // this method will:
-  // - add the ProgId entries to HKCU on XP. HKCU entries will not make
-  //   Chrome show in Set Program Access and Defaults but they are still useful
-  //   because we can make Chrome run when user clicks on http link or html
-  //   file.
-  // - will try to launch setup.exe with admin priviledges on Vista to do
-  //   these tasks. Users will see standard Vista elevation prompt and if they
-  //   enter the right credentials, the write operation will work.
+  // This method first checks if Chrome is fully registered (as outlined below)

[grt (UTC plus 2), 2012/06/08 18:01:21]

Please begin the comment with what the function does (e.g., "Registers Chrome as
a potential default browser and handler for filetypes and protocols.") and then
follow with the details.  This gives the reader the most important info
up-front.

[gab, 2012/06/11 16:19:55]

Done.

+  // on Windows. If it is, this method is a no-op; if it isn't, this method
+  // registers Chrome so that it shows up in the list of Default Programs with
+  // the protocols and file types it can handle by default (ref:
+  // ShellUtil::kPotentialProtocolAssociations + ShellUtil::kFileAssociations).
+  // TODO(gab): This should be ShellUtil::kBrowserProtocolAssociations (i.e. not

[grt (UTC plus 2), 2012/06/08 18:01:21]

Avoid implementation details like this in doc comments; keep it to what the
caller really needs to know.  References like this to the implementation details
means that this documentation comment will either require future maintenance or
become stale.  The reader will know where to find the source if they're curious
(the corresponding .cc file), so I don't see an upside to putting this here. 
See the "Function Comments" section of the Google C++ style guide for more.

[gab, 2012/06/11 16:19:55]

Done.

+  // ShellUtil::kPotentialProtocolAssociations) once http://crbug.com/122756 is
+  // fixed.
+  // This method requires write access to HKLM so is just a best effort deal.
+  // If write to HKLM fails and:
+  // - elevate_if_not_admin is true (and we are on Vista and above):
+  //   this method will try to launch setup.exe with admin priviledges (by
+  //   prompting the user with a UAC) to do these tasks.
+  // - elevate_if_not_admin is false (or we are on XP):
+  //   add the ProgId entries to HKCU. These entries will not make Chrome show
+  //   in Set Program Access and Defaults but they are still useful because we
+  //   can make Chrome run when user clicks on http link or html file.
   // Currently elevate_if_not_admin is true only when user tries to make Chrome
-  // default browser (through the UI or through installer options) and Chrome
-  // is not registered on the machine.
+  // default browser (through the UI or through installer options).
   //
   // |chrome_exe| full path to chrome.exe.
   // |unique_suffix| Optional input. If given, this function appends the value
   // to default browser entries names that it creates in the registry.
+  // Currently, this is only used to continue an install with the same suffix
+  // when elevating and calling setup.exe with admin privileges as described
+  // above.
   // |elevate_if_not_admin| if true will make this method try alternate methods
   // as described above.
+  //
+  // Returns true if Chrome is successfully registered (or already registered).
   static bool RegisterChromeBrowser(BrowserDistribution* dist,
                                     const string16& chrome_exe,
                                     const string16& unique_suffix,