Fix RegisterChromeBrowser definition and usage in shell_util

chrome/installer/util/shell_util.h

 // 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.
 //
 // This file declares methods that are useful for integrating Chrome in
 // Windows shell. These methods are all static and currently part of
 // ShellUtil class.
 
 #ifndef CHROME_INSTALLER_UTIL_SHELL_UTIL_H_
 #define CHROME_INSTALLER_UTIL_SHELL_UTIL_H_
@@ skipping 226 matching lines @@
                                 const string16& chrome_exe,
                                 bool elevate_if_not_admin);
 
   // Make Chrome the default application for a protocol.
   // chrome_exe: The chrome.exe path to register as default browser.
   // protocol: The protocol to register as the default handler for.
   static bool MakeChromeDefaultProtocolClient(BrowserDistribution* dist,
                                               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,
                                     bool elevate_if_not_admin);
 
   // This method declares to Windows that Chrome is capable of handling the
   // given protocol. This function will call the RegisterChromeBrowser function
   // to register with Windows as capable of handling the protocol, if it isn't
   // currently registered as capable.
   // Declaring the capability of handling a protocol is necessary to register
@@ skipping 66 matching lines @@
                                    const string16& icon_path,
                                    int icon_index,
                                    uint32 options);
 
  private:
   DISALLOW_COPY_AND_ASSIGN(ShellUtil);
 };
 
 
 #endif  // CHROME_INSTALLER_UTIL_SHELL_UTIL_H_