diff --git a/include/git2/repository.h b/include/git2/repository.h
index f1b55f433..e91108a33 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -238,7 +238,7 @@ typedef enum {
  *        repository initialization is completed, an "origin" remote
  *        will be added pointing to this URL.
  */
-typedef struct git_repository_init_options {
+typedef struct {
 	uint32_t    flags;
 	uint32_t    mode;
 	const char *workdir_path;
@@ -269,6 +269,10 @@ GIT_EXTERN(int) git_repository_init_ext(
 /**
  * Retrieve and resolve the reference pointed at by HEAD.
  *
+ * The returned `git_reference` will be owned by caller and
+ * `git_reference_free()` must be called when done with it to release the
+ * allocated memory and prevent a leak.
+ *
  * @param out pointer to the reference which will be retrieved
  * @param repo a repository object
  *
diff --git a/include/git2/signature.h b/include/git2/signature.h
index 01a6dfb44..7a265bd8e 100644
--- a/include/git2/signature.h
+++ b/include/git2/signature.h
@@ -20,8 +20,9 @@
 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.
@@ -36,8 +37,9 @@ GIT_BEGIN_DECL
 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 out new signature, in case of error NULL
  * @param name name of the person
@@ -48,9 +50,10 @@ GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const c
 
 
 /**
- * Create a copy of an existing signature.  All internal strings are also duplicated.
- * The caller is responsible for freeing this structure with
- * git_signature_free.
+ * Create a copy of an existing signature.  All internal strings are also
+ * duplicated.
+ *
+ * Call `git_signature_free()` to free the data.
  *
  * @param sig signature to duplicated
  * @return a copy of sig, NULL on out of memory
@@ -58,7 +61,11 @@ GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const c
 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
  */