Merge pull request #1087 from libgit2/great-renaming

The Great Renaming of 2012

1 files changed, 19 insertions, 11 deletions

diff --git a/include/git2/signature.h b/include/git2/signature.h
index cdbe67879..7a265bd8e 100644
--- a/include/git2/signature.h
+++ b/include/git2/signature.h
@@ -20,44 +20,52 @@
 GIT_BEGIN_DECL
 
 /**
- * Create a new action signature. The signature must be freed
- * manually or using git_signature_free
+ * Create a new action signature.
+ *
+ * Call `git_signature_free()` to free the data.
  *
  * Note: angle brackets ('<' and '>') characters are not allowed
  * to be used in either the `name` or the `email` parameter.
  *
- * @param sig_out new signature, in case of error NULL
+ * @param out new signature, in case of error NULL
  * @param name name of the person
  * @param email email of the person
  * @param time time when the action happened
  * @param offset timezone offset in minutes for the time
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_signature_new(git_signature **sig_out, const char *name, const char *email, git_time_t time, int offset);
+GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const char *email, git_time_t time, int offset);
 
 /**
- * Create a new action signature with a timestamp of 'now'. The
- * signature must be freed manually or using git_signature_free
+ * Create a new action signature with a timestamp of 'now'.
+ *
+ * Call `git_signature_free()` to free the data.
  *
- * @param sig_out new signature, in case of error NULL
+ * @param out new signature, in case of error NULL
  * @param name name of the person
  * @param email email of the person
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_signature_now(git_signature **sig_out, const char *name, const char *email);
+GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const char *email);
 
 
 /**
- * Create a copy of an existing signature.
+ * Create a copy of an existing signature.  All internal strings are also
+ * duplicated.
+ *
+ * Call `git_signature_free()` to free the data.
  *
- * All internal strings are also duplicated.
  * @param sig signature to duplicated
  * @return a copy of sig, NULL on out of memory
  */
 GIT_EXTERN(git_signature *) git_signature_dup(const git_signature *sig);
 
 /**
- * Free an existing signature
+ * Free an existing signature.
+ *
+ * Because the signature is not an opaque structure, it is legal to free it
+ * manually, but be sure to free the "name" and "email" strings in addition
+ * to the structure itself.
  *
  * @param sig signature to free
  */