google_apis: Clean up base_operations.h

chrome/browser/google_apis/base_operations.h

Index: chrome/browser/google_apis/base_operations.h
diff --git a/chrome/browser/google_apis/base_operations.h b/chrome/browser/google_apis/base_operations.h
index 9121e415357673122020dfa2c0ddeb94ffaf5a86..83c7a4101879856a419b4990f0cd509f5a045387 100644
--- a/chrome/browser/google_apis/base_operations.h
+++ b/chrome/browser/google_apis/base_operations.h
@@ -1,6 +1,8 @@
 // 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 provides base classes used to implement operations for Google APIs.
 
 #ifndef CHROME_BROWSER_GOOGLE_APIS_BASE_OPERATIONS_H_
 #define CHROME_BROWSER_GOOGLE_APIS_BASE_OPERATIONS_H_
@@ -27,7 +29,8 @@ namespace google_apis {
 
 //======================= AuthenticatedOperationInterface ======================
 
-// An interface for implementing an operation used by DriveServiceInterface.
+// An interface class for implementing an operation which requires OAuth2
+// authentication.
 class AuthenticatedOperationInterface {
  public:
   // Callback to DriveServiceInterface upon for re-authentication.
@@ -47,6 +50,8 @@ class AuthenticatedOperationInterface {
 
   // Sets the callback to DriveServiceInterface when the operation restarts due
   // to an authentication failure.
+  // This function should be called before Start().
+  // TODO(satorux): Make it a parameter of Start(). crbug.com/163535.
   virtual void SetReAuthenticateCallback(
       const ReAuthenticateCallback& callback) = 0;
 
@@ -70,32 +75,34 @@ class UrlFetchOperationBase : public AuthenticatedOperationInterface,
                               public OperationRegistry::Operation,
                               public net::URLFetcherDelegate {
  public:
-  // Overridden from AuthenticatedOperationInterface.
+  // AuthenticatedOperationInterface overrides.
   virtual void Start(const std::string& auth_token,
                      const std::string& custom_user_agent) OVERRIDE;
-
-  // Overridden from AuthenticatedOperationInterface.
   virtual void SetReAuthenticateCallback(
       const ReAuthenticateCallback& callback) OVERRIDE;
-
-  // Overridden from AuthenticatedOperationInterface.
   virtual base::WeakPtr<AuthenticatedOperationInterface> GetWeakPtr() OVERRIDE;
 
  protected:
   explicit UrlFetchOperationBase(OperationRegistry* registry);
+  // Use this constructor when you need to implement operations that take a
+  // drive file path (ex. for downloading and uploading).
+  // TODO(satorux): Remove the drive file path hack. crbug.com/163296
   UrlFetchOperationBase(OperationRegistry* registry,
                         OperationType type,
-                        const FilePath& path);
+                        const FilePath& drive_file_path);
   virtual ~UrlFetchOperationBase();
 
   // Gets URL for the request.
   virtual GURL GetURL() const = 0;
+
   // Returns the request type. A derived class should override this method
   // for a request type other than HTTP GET.
   virtual net::URLFetcher::RequestType GetRequestType() const;
+
   // Returns the extra HTTP headers for the request. A derived class should
   // override this method to specify any extra headers needed for the request.
   virtual std::vector<std::string> GetExtraRequestHeaders() const;
+
   // Used by a derived class to add any content data to the request.
   // Returns true if |upload_content_type| and |upload_content| are updated
   // with the content type and data for the request.
@@ -116,29 +123,30 @@ class UrlFetchOperationBase : public AuthenticatedOperationInterface,
   // an user operation. Must be implemented by a derived class.
   virtual void RunCallbackOnPrematureFailure(GDataErrorCode code) = 0;
 
-  // Implement OperationRegistry::Operation
-  virtual void DoCancel() OVERRIDE;
-
-  // Overridden from URLFetcherDelegate.
-  virtual void OnURLFetchComplete(const net::URLFetcher* source) OVERRIDE;
-
-  // Overridden from AuthenticatedOperationInterface.
-  virtual void OnAuthFailed(GDataErrorCode code) OVERRIDE;
-
   // Invoked when ProcessURLFetchResults() is completed.
   void OnProcessURLFetchResultsComplete(bool result);
 
   // Returns an appropriate GDataErrorCode based on the HTTP response code and
   // the status of the URLFetcher.
-  GDataErrorCode GetErrorCode(const net::URLFetcher* source) const;
+  static GDataErrorCode GetErrorCode(const net::URLFetcher* source);
+
+  // The following members are used by DownloadFileOperation.
+  // TODO(satorux): Make them private.
+  bool save_temp_file_;
+  FilePath output_file_path_;
+
+ private:
+  // OperationRegistry::Operation overrides.
+  virtual void DoCancel() OVERRIDE;
+
+  // URLFetcherDelegate overrides.
+  virtual void OnURLFetchComplete(const net::URLFetcher* source) OVERRIDE;
 
-  std::string GetResponseHeadersAsString(
-      const net::URLFetcher* url_fetcher);
+  // AuthenticatedOperationInterface overrides.
+  virtual void OnAuthFailed(GDataErrorCode code) OVERRIDE;
 
   ReAuthenticateCallback re_authenticate_callback_;
   int re_authenticate_count_;
-  bool save_temp_file_;
-  FilePath output_file_path_;
   scoped_ptr<net::URLFetcher> url_fetcher_;
   bool started_;
 
@@ -167,7 +175,7 @@ class EntryActionOperation : public UrlFetchOperationBase {
   virtual void RunCallbackOnPrematureFailure(GDataErrorCode code) OVERRIDE;
 
  private:
-  EntryActionCallback callback_;
+  const EntryActionCallback callback_;
 
   DISALLOW_COPY_AND_ASSIGN(EntryActionOperation);
 };
@@ -180,31 +188,37 @@ class EntryActionOperation : public UrlFetchOperationBase {
 typedef base::Callback<void(GDataErrorCode error,
                             scoped_ptr<base::Value> feed_data)> GetDataCallback;
 
-// This class performs the operation for fetching and parsing JSON data content.
+// This class performs the operation for fetching and converting the fetched
+// content into a base::Value.
 class GetDataOperation : public UrlFetchOperationBase {
  public:
   GetDataOperation(OperationRegistry* registry,
                    const GetDataCallback& callback);
   virtual ~GetDataOperation();
 
-  // Parse GData JSON response.
+  // Parses JSON response. A derived class should override this function if
+  // the input data is not JSON (ex. XML).
   virtual void ParseResponse(GDataErrorCode fetch_error_code,
                              const std::string& data);
 
- protected:
-  // Overridden from UrlFetchOperationBase.
+  // UrlFetchOperationBase overrides.
   virtual void ProcessURLFetchResults(const net::URLFetcher* source) OVERRIDE;
-  virtual void RunCallbackOnPrematureFailure(
-      GDataErrorCode fetch_error_code) OVERRIDE;
+
+  // Runs |callback_| with the given parameters, if |callback_| is not null.
+  // TODO(satorux): Remove this by making |callback_| mandatory.
   void RunCallback(GDataErrorCode fetch_error_code,
                    scoped_ptr<base::Value> value);
 
  private:
+  // UrlFetchOperationBase overrides.
+  virtual void RunCallbackOnPrematureFailure(
+      GDataErrorCode fetch_error_code) OVERRIDE;
+
   // Called when ParseJsonOnBlockingPool() is completed.
   void OnDataParsed(google_apis::GDataErrorCode fetch_error_code,
                     scoped_ptr<base::Value> value);
 
-  GetDataCallback callback_;
+  const GetDataCallback callback_;
 
   // Note: This should remain the last member so it'll be destroyed and
   // invalidate its weak pointers before any other members are destroyed.