API updates for tag.h

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);
 
 
 /**
@@ -279,34 +282,34 @@ GIT_EXTERN(int) git_tag_list_match(
 	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_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

src/refs.c

@@ -647,7 +647,7 @@ static int packed_find_peel(git_repository *repo, struct packref *ref)
 		/*
 		 * Find the object pointed at by this tag
 		 */
-		git_oid_cpy(&ref->peel, git_tag_target_oid(tag));
+		git_oid_cpy(&ref->peel, git_tag_target_id(tag));
 		ref->flags |= GIT_PACKREF_HAS_PEEL;
 
 		/*

src/tag.c

@@ -22,41 +22,41 @@ void git_tag__free(git_tag *tag)
 	git__free(tag);
 }
 
-const git_oid *git_tag_id(git_tag *c)
+const git_oid *git_tag_id(const git_tag *c)
 {
-	return git_object_id((git_object *)c);
+	return git_object_id((const git_object *)c);
 }
 
-int git_tag_target(git_object **target, git_tag *t)
+int git_tag_target(git_object **target, const git_tag *t)
 {
 	assert(t);
 	return git_object_lookup(target, t->object.repo, &t->target, t->type);
 }
 
-const git_oid *git_tag_target_oid(git_tag *t)
+const git_oid *git_tag_target_id(const git_tag *t)
 {
 	assert(t);
 	return &t->target;
 }
 
-git_otype git_tag_target_type(git_tag *t)
+git_otype git_tag_target_type(const git_tag *t)
 {
 	assert(t);
 	return t->type;
 }
 
-const char *git_tag_name(git_tag *t)
+const char *git_tag_name(const git_tag *t)
 {
 	assert(t);
 	return t->tag_name;
 }
 
-const git_signature *git_tag_tagger(git_tag *t)
+const git_signature *git_tag_tagger(const git_tag *t)
 {
 	return t->tagger;
 }
 
-const char *git_tag_message(git_tag *t)
+const char *git_tag_message(const git_tag *t)
 {
 	assert(t);
 	return t->message;
@@ -425,8 +425,8 @@ int git_tag_foreach(git_repository *repo, git_tag_foreach_cb cb, void *cb_data)
 	data.cb_data = cb_data;
 	data.repo = repo;
 
-	return git_reference_foreach(repo, GIT_REF_OID | GIT_REF_PACKED,
-				     &tags_cb, &data);
+	return git_reference_foreach(
+		repo, GIT_REF_OID | GIT_REF_PACKED, &tags_cb, &data);
 }
 
 typedef struct {
@@ -477,7 +477,7 @@ int git_tag_list(git_strarray *tag_names, git_repository *repo)
 	return git_tag_list_match(tag_names, "", repo);
 }
 
-int git_tag_peel(git_object **tag_target, git_tag *tag)
+int git_tag_peel(git_object **tag_target, const git_tag *tag)
 {
-	return git_object_peel(tag_target, (git_object *)tag, GIT_OBJ_ANY);
+	return git_object_peel(tag_target, (const git_object *)tag, GIT_OBJ_ANY);
 }

tests-clar/object/tag/write.c

@@ -45,7 +45,7 @@ void test_object_tag_write__basic(void)
 	git_signature_free(tagger);
 
 	cl_git_pass(git_tag_lookup(&tag, g_repo, &tag_id));
-	cl_assert(git_oid_cmp(git_tag_target_oid(tag), &target_id) == 0);
+	cl_assert(git_oid_cmp(git_tag_target_id(tag), &target_id) == 0);
 
 	/* Check attributes were set correctly */
 	tagger1 = git_tag_tagger(tag);