base/win: Add documentation to RegKey::Read/Write functions.

base/win/registry.h

Index: base/win/registry.h
diff --git a/base/win/registry.h b/base/win/registry.h
index 33052ff6bb0419d40a6c52022a445ebb87dde3bd..54131045585db86db3df03b8fd05a7f6afe32f81 100644
--- a/base/win/registry.h
+++ b/base/win/registry.h
@@ -66,16 +66,36 @@ class BASE_EXPORT RegKey {
   // Deletes a single value within the key.
   LONG DeleteValue(const wchar_t* name);
 
-  LONG ReadValue(const wchar_t* name, void* data, DWORD* dsize,
+  // Getters:

[M-A Ruel, 2011/10/18 18:34:14]

I feel like the comments don't add much. The signature is describing what it
does well enough. That's probably there wasn't in the first place. Sincerely,
I'm not sure about this change at all.

[tfarina, 2011/10/18 18:40:43]

Like I said in the first email I was trying to make it closer to Omaha API. And
it seems is just me that is seeing the benefit to make this clean (easier to
read) and not a *mess* like it's now! And yes the order is particular, it is in
an order of complexity (int, int64, string, ...); 

Please, take a look at their API here:
http://code.google.com/p/omaha/source/browse/trunk/base/reg_key.h

+
+  // Returns an int32 value.

[grt (UTC plus 2), 2011/10/18 19:59:33]

Comments here would be useful to explain the corner cases: e.g., I assume that
null or empty string for |name| means read the key's default value.  The comment
doesn't say if one or both is valid, so I have to look in the implementation to
figure it out.

[tfarina, 2011/10/18 20:24:30]

Exactly. If |name| is NULL or empty it retrieves the default value, if any.

And it will returns ERROR_FILE_NOT_FOUND if the value for |name| does not exist.

[tfarina, 2011/10/19 01:39:07]

Comment added. Please, take another look.

+  LONG ReadValueDW(const wchar_t* name, DWORD* out_value) const;
+
+  // Returns an int64 value.
+  LONG ReadInt64(const wchar_t* name, int64* out_value) const;
+
+  // Returns a string value.
+  LONG ReadValue(const wchar_t* name, std::wstring* out_value) const;
+
+  // Returns raw data.
+  LONG ReadValue(const wchar_t* name,
+                 void* data,
+                 DWORD* dsize,
                  DWORD* dtype) const;
-  LONG ReadValue(const wchar_t* name, std::wstring* value) const;
-  LONG ReadValueDW(const wchar_t* name, DWORD* value) const;
-  LONG ReadInt64(const wchar_t* name, int64* value) const;
 
-  LONG WriteValue(const wchar_t* name, const void* data, DWORD dsize,
+  // Setters:
+
+  // Sets an int32 value.
+  LONG WriteValue(const wchar_t* name, DWORD in_value);
+
+  // Sets a string value.
+  LONG WriteValue(const wchar_t* name, const wchar_t* in_value);
+
+  // Sets raw data, including type.
+  LONG WriteValue(const wchar_t* name,
+                  const void* data,
+                  DWORD dsize,
                   DWORD dtype);
-  LONG WriteValue(const wchar_t* name, const wchar_t* value);
-  LONG WriteValue(const wchar_t* name, DWORD value);
 
   // Starts watching the key to see if any of its values have changed.
   // The key must have been opened with the KEY_NOTIFY access privilege.