API updates for tag.h

2 files changed, 59 insertions, 56 deletions

diff --git a/include/git2/object.h b/include/git2/object.h
index 69af392a0..fcc56cb27 100644
--- a/include/git2/object.h
+++ b/include/git2/object.h
@@ -183,9 +183,9 @@ GIT_EXTERN(size_t) git_object__size(git_otype type);
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_object_peel(
-		git_object **peeled,
-		const git_object *object,
-		git_otype target_type);
+	git_object **peeled,
+	const git_object *object,
+	git_otype target_type);
 
 /** @} */
 GIT_END_DECL
diff --git a/include/git2/tag.h b/include/git2/tag.h
index a1b685f12..f82a6c9f9 100644
--- a/include/git2/tag.h
+++ b/include/git2/tag.h
@@ -25,14 +25,16 @@ GIT_BEGIN_DECL
 /**
  * Lookup a tag object from the repository.
  *
- * @param tag pointer to the looked up tag
+ * @param out pointer to the looked up tag
  * @param repo the repo to use when locating the tag.
  * @param id identity of the tag to locate.
  * @return 0 or an error code
  */
-GIT_INLINE(int) git_tag_lookup(git_tag **tag, git_repository *repo, const git_oid *id)
+GIT_INLINE(int) git_tag_lookup(
+	git_tag **out, git_repository *repo, const git_oid *id)
 {
-	return git_object_lookup((git_object **)tag, repo, id, (git_otype)GIT_OBJ_TAG);
+	return git_object_lookup(
+		(git_object **)out, repo, id, (git_otype)GIT_OBJ_TAG);
 }
 
 /**
@@ -41,32 +43,33 @@ GIT_INLINE(int) git_tag_lookup(git_tag **tag, git_repository *repo, const git_oi
  *
  * @see git_object_lookup_prefix
  *
- * @param tag pointer to the looked up tag
+ * @param out pointer to the looked up tag
  * @param repo the repo to use when locating the tag.
  * @param id identity of the tag to locate.
  * @param len the length of the short identifier
  * @return 0 or an error code
  */
-GIT_INLINE(int) git_tag_lookup_prefix(git_tag **tag, git_repository *repo, const git_oid *id, size_t len)
+GIT_INLINE(int) git_tag_lookup_prefix(
+	git_tag **out, git_repository *repo, const git_oid *id, size_t len)
 {
-	return git_object_lookup_prefix((git_object **)tag, repo, id, len, (git_otype)GIT_OBJ_TAG);
+	return git_object_lookup_prefix(
+		(git_object **)out, repo, id, len, (git_otype)GIT_OBJ_TAG);
 }
 
 /**
  * Close an open tag
  *
- * This is a wrapper around git_object_free()
+ * You can no longer use the git_tag pointer after this call.
  *
- * IMPORTANT:
- * It *is* necessary to call this method when you stop
- * using a tag. Failure to do so will cause a memory leak.
+ * IMPORTANT: You MUST call this method when you are through with a tag to
+ * release memory. Failure to do so will cause a memory leak.
  *
  * @param tag the tag to close
  */
 
 GIT_INLINE(void) git_tag_free(git_tag *tag)
 {
-	git_object_free((git_object *) tag);
+	git_object_free((git_object *)tag);
 }
 
 
@@ -76,7 +79,7 @@ GIT_INLINE(void) git_tag_free(git_tag *tag)
  * @param tag a previously loaded tag.
  * @return object identity for the tag.
  */
-GIT_EXTERN(const git_oid *) git_tag_id(git_tag *tag);
+GIT_EXTERN(const git_oid *) git_tag_id(const git_tag *tag);
 
 /**
  * Get the tagged object of a tag
@@ -84,11 +87,11 @@ GIT_EXTERN(const git_oid *) git_tag_id(git_tag *tag);
  * This method performs a repository lookup for the
  * given object and returns it
  *
- * @param target pointer where to store the target
+ * @param target_out pointer where to store the target
  * @param tag a previously loaded tag.
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_tag_target(git_object **target, git_tag *tag);
+GIT_EXTERN(int) git_tag_target(git_object **target_out, const git_tag *tag);
 
 /**
  * Get the OID of the tagged object of a tag
@@ -96,7 +99,7 @@ GIT_EXTERN(int) git_tag_target(git_object **target, git_tag *tag);
  * @param tag a previously loaded tag.
  * @return pointer to the OID
  */
-GIT_EXTERN(const git_oid *) git_tag_target_oid(git_tag *tag);
+GIT_EXTERN(const git_oid *) git_tag_target_id(const git_tag *tag);
 
 /**
  * Get the type of a tag's tagged object
@@ -104,7 +107,7 @@ GIT_EXTERN(const git_oid *) git_tag_target_oid(git_tag *tag);
  * @param tag a previously loaded tag.
  * @return type of the tagged object
  */
-GIT_EXTERN(git_otype) git_tag_target_type(git_tag *tag);
+GIT_EXTERN(git_otype) git_tag_target_type(const git_tag *tag);
 
 /**
  * Get the name of a tag
@@ -112,7 +115,7 @@ GIT_EXTERN(git_otype) git_tag_target_type(git_tag *tag);
  * @param tag a previously loaded tag.
  * @return name of the tag
  */
-GIT_EXTERN(const char *) git_tag_name(git_tag *tag);
+GIT_EXTERN(const char *) git_tag_name(const git_tag *tag);
 
 /**
  * Get the tagger (author) of a tag
@@ -120,7 +123,7 @@ GIT_EXTERN(const char *) git_tag_name(git_tag *tag);
  * @param tag a previously loaded tag.
  * @return reference to the tag's author
  */
-GIT_EXTERN(const git_signature *) git_tag_tagger(git_tag *tag);
+GIT_EXTERN(const git_signature *) git_tag_tagger(const git_tag *tag);
 
 /**
  * Get the message of a tag
@@ -128,7 +131,7 @@ GIT_EXTERN(const git_signature *) git_tag_tagger(git_tag *tag);
  * @param tag a previously loaded tag.
  * @return message of the tag
  */
-GIT_EXTERN(const char *) git_tag_message(git_tag *tag);
+GIT_EXTERN(const char *) git_tag_message(const git_tag *tag);
 
 
 /**
@@ -167,13 +170,13 @@ GIT_EXTERN(const char *) git_tag_message(git_tag *tag);
  *	is written in the /refs/tags folder, pointing to it
  */
 GIT_EXTERN(int) git_tag_create(
-		git_oid *oid,
-		git_repository *repo,
-		const char *tag_name,
-		const git_object *target,
-		const git_signature *tagger,
-		const char *message,
-		int force);
+	git_oid *oid,
+	git_repository *repo,
+	const char *tag_name,
+	const git_object *target,
+	const git_signature *tagger,
+	const char *message,
+	int force);
 
 /**
  * Create a new tag in the repository from a buffer
@@ -185,10 +188,10 @@ GIT_EXTERN(int) git_tag_create(
  * @return 0 on success; error code otherwise
  */
 GIT_EXTERN(int) git_tag_create_frombuffer(
-		git_oid *oid,
-		git_repository *repo,
-		const char *buffer,
-		int force);
+	git_oid *oid,
+	git_repository *repo,
+	const char *buffer,
+	int force);
 
 /**
  * Create a new lightweight tag pointing at a target object
@@ -218,11 +221,11 @@ GIT_EXTERN(int) git_tag_create_frombuffer(
  * pointing to the provided target object
  */
 GIT_EXTERN(int) git_tag_create_lightweight(
-		git_oid *oid,
-		git_repository *repo,
-		const char *tag_name,
-		const git_object *target,
-		int force);
+	git_oid *oid,
+	git_repository *repo,
+	const char *tag_name,
+	const git_object *target,
+	int force);
 
 /**
  * Delete an existing tag reference.
@@ -235,8 +238,8 @@ GIT_EXTERN(int) git_tag_create_lightweight(
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_tag_delete(
-		git_repository *repo,
-		const char *tag_name);
+	git_repository *repo,
+	const char *tag_name);
 
 /**
  * Fill a list with all the tags in the Repository
@@ -252,8 +255,8 @@ GIT_EXTERN(int) git_tag_delete(
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_tag_list(
-		git_strarray *tag_names,
-		git_repository *repo);
+	git_strarray *tag_names,
+	git_repository *repo);
 
 /**
  * Fill a list with all the tags in the Repository
@@ -274,39 +277,39 @@ GIT_EXTERN(int) git_tag_list(
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_tag_list_match(
-		git_strarray *tag_names,
-		const char *pattern,
-		git_repository *repo);
+	git_strarray *tag_names,
+	const char *pattern,
+	git_repository *repo);
 
 
-typedef int (*git_tag_foreach_cb)(const char *name, git_oid *oid, void *data);
+typedef int (*git_tag_foreach_cb)(const char *name, git_oid *oid, void *payload);
+
 /**
  * Call callback `cb' for each tag in the repository
  *
  * @param repo Repository
- * @param cb Callback function
- * @param cb_data Pointer to callback data (optional)
+ * @param callback Callback function
+ * @param payload Pointer to callback data (optional)
  */
 GIT_EXTERN(int) git_tag_foreach(
-		git_repository *repo,
-		git_tag_foreach_cb cb,
-		void *cb_data);
+	git_repository *repo,
+	git_tag_foreach_cb callback,
+	void *payload);
 
 
 /**
- * Recursively peel a tag until a non tag git_object
- * is met
+ * Recursively peel a tag until a non tag git_object is found
  *
  * The retrieved `tag_target` object is owned by the repository
  * and should be closed with the `git_object_free` method.
  *
- * @param tag_target Pointer to the peeled git_object
+ * @param tag_target_out Pointer to the peeled git_object
  * @param tag The tag to be processed
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_tag_peel(
-		git_object **tag_target,
-		git_tag *tag);
+	git_object **tag_target_out,
+	const git_tag *tag);
 
 /** @} */
 GIT_END_DECL