dbus: Add comments about object ownership

BUG=163231
TEST=none

Review URL: https://codereview.chromium.org/11416252

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@170117 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 21 insertions, 14 deletions

diff --git a/dbus/exported_object.h b/dbus/exported_object.h
index 9d3164f..4e74ddb 100644
--- a/dbus/exported_object.h
+++ b/dbus/exported_object.h
@@ -38,22 +38,29 @@ class CHROME_DBUS_EXPORT ExportedObject
   // constructor.
   ExportedObject(Bus* bus, const ObjectPath& object_path);
 
-  // Called to send a response from an exported method. Response* is the
-  // response message. Callers should pass a NULL Response* in the event
-  // of an error that prevents the sending of a response.
-  typedef base::Callback<void (Response*)> ResponseSender;
-
-  // Called when an exported method is called. MethodCall* is the request
-  // message. ResponseSender is the callback that should be used to send a
-  // response.
-  typedef base::Callback<void (MethodCall*, ResponseSender)> MethodCallCallback;
+  // Called to send a response from an exported method. |response| is the
+  // response message. Callers should pass NULL in the event of an error that
+  // prevents the sending of a response.
+  //
+  // ResponseSender takes ownership of |response| hence client code should
+  // not delete |response|.
+  // TODO(satorux): Change this to take scoped_ptr<Response> to make
+  // ownership clearer. crbug.com/163231
+  typedef base::Callback<void (Response* response)> ResponseSender;
+
+  // Called when an exported method is called. |method_call| is the request
+  // message. |sender| is the callback that's used to send a response.
+  //
+  // |method_call| is owned by ExportedObject, hence client code should not
+  // delete |method_call|.
+  typedef base::Callback<void (MethodCall* method_call, ResponseSender sender)>
+      MethodCallCallback;
 
   // Called when method exporting is done.
-  // Parameters:
-  // - the interface name.
-  // - the method name.
-  // - whether exporting was successful or not.
-  typedef base::Callback<void (const std::string&, const std::string&, bool)>
+  // |success| indicates whether exporting was successful or not.
+  typedef base::Callback<void (const std::string& interface_name,
+                               const std::string& method_name,
+                               bool success)>
       OnExportedCallback;
 
   // Exports the method specified by |interface_name| and |method_name|,