Rename ref and reflog apis for consistency

3 files changed, 49 insertions, 44 deletions

diff --git a/include/git2/pack.h b/include/git2/pack.h
index 94d5fc6a1..585cffef6 100644
--- a/include/git2/pack.h
+++ b/include/git2/pack.h
@@ -38,8 +38,9 @@ GIT_EXTERN(int) git_packbuilder_new(git_packbuilder **out, git_repository *repo)
  *
  * @param pb The packbuilder
  * @param n Number of threads to spawn
+ * @return number of actual threads to be used
  */
-GIT_EXTERN(void) git_packbuilder_set_threads(git_packbuilder *pb, unsigned int n);
+GIT_EXTERN(unsigned int) git_packbuilder_set_threads(git_packbuilder *pb, unsigned int n);
 
 /**
  * Insert a single object
@@ -48,12 +49,12 @@ GIT_EXTERN(void) git_packbuilder_set_threads(git_packbuilder *pb, unsigned int n
  * commits followed by trees and blobs.
  *
  * @param pb The packbuilder
- * @param oid The oid of the commit
- * @param oid The name; might be NULL
+ * @param id The oid of the commit
+ * @param name The name; might be NULL
  *
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_packbuilder_insert(git_packbuilder *pb, const git_oid *oid,	const char *name);
+GIT_EXTERN(int) git_packbuilder_insert(git_packbuilder *pb, const git_oid *id, const char *name);
 
 /**
  * Insert a root tree object
@@ -61,11 +62,11 @@ GIT_EXTERN(int) git_packbuilder_insert(git_packbuilder *pb, const git_oid *oid,
  * This will add the tree as well as all referenced trees and blobs.
  *
  * @param pb The packbuilder
- * @param oid The oid of the root tree
+ * @param id The oid of the root tree
  *
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_packbuilder_insert_tree(git_packbuilder *pb, const git_oid *oid);
+GIT_EXTERN(int) git_packbuilder_insert_tree(git_packbuilder *pb, const git_oid *id);
 
 /**
  * Write the new pack and the corresponding index to path
@@ -82,15 +83,17 @@ GIT_EXTERN(int) git_packbuilder_write(git_packbuilder *pb, const char *file);
  *
  * @param pb the packbuilder
  * @param cb the callback to call with each packed object's buffer
- * @param data the callback's data
+ * @param payload the callback's data
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_packbuilder_foreach(git_packbuilder *pb, int (*cb)(void *buf, size_t size, void *data), void *data);
+typedef int (*git_packbuilder_foreach_cb)(void *buf, size_t size, void *payload);
+GIT_EXTERN(int) git_packbuilder_foreach(git_packbuilder *pb, git_packbuilder_foreach_cb cb, void *payload);
 
 /**
  * Get the total number of objects the packbuilder will write out
  *
  * @param pb the packbuilder
+ * @return
  */
 GIT_EXTERN(uint32_t) git_packbuilder_object_count(git_packbuilder *pb);
 
@@ -98,6 +101,7 @@ GIT_EXTERN(uint32_t) git_packbuilder_object_count(git_packbuilder *pb);
  * Get the number of objects the packbuilder has already written out
  *
  * @param pb the packbuilder
+ * @return
  */
 GIT_EXTERN(uint32_t) git_packbuilder_written(git_packbuilder *pb);
 
diff --git a/include/git2/reflog.h b/include/git2/reflog.h
index 72e1f1753..45dff2165 100644
--- a/include/git2/reflog.h
+++ b/include/git2/reflog.h
@@ -30,11 +30,11 @@ GIT_BEGIN_DECL
  * The reflog must be freed manually by using
  * git_reflog_free().
  *
- * @param reflog pointer to reflog
+ * @param out pointer to reflog
  * @param ref reference to read the reflog for
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_reflog_read(git_reflog **reflog, git_reference *ref);
+GIT_EXTERN(int) git_reflog_read(git_reflog **out, const git_reference *ref);
 
 /**
  * Write an existing in-memory reflog object back to disk
@@ -51,12 +51,12 @@ GIT_EXTERN(int) git_reflog_write(git_reflog *reflog);
  * `msg` is optional and can be NULL.
  *
  * @param reflog an existing reflog object
- * @param new_oid the OID the reference is now pointing to
+ * @param id the OID the reference is now pointing to
  * @param committer the signature of the committer
  * @param msg the reflog message
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *new_oid, const git_signature *committer, const char *msg);
+GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *id, const git_signature *committer, const char *msg);
 
 /**
  * Rename the reflog for the given reference
@@ -64,10 +64,10 @@ GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *new_oid, co
  * The reflog to be renamed is expected to already exist
  *
  * @param ref the reference
- * @param new_name the new name of the reference
+ * @param name the new name of the reference
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_reflog_rename(git_reference *ref, const char *new_name);
+GIT_EXTERN(int) git_reflog_rename(git_reference *ref, const char *name);
 
 /**
  * Delete the reflog for the given reference
@@ -83,7 +83,7 @@ GIT_EXTERN(int) git_reflog_delete(git_reference *ref);
  * @param reflog the previously loaded reflog
  * @return the number of log entries
  */
-GIT_EXTERN(unsigned int) git_reflog_entrycount(git_reflog *reflog);
+GIT_EXTERN(size_t) git_reflog_entrycount(git_reflog *reflog);
 
 /**
  * Lookup an entry by its index
@@ -126,7 +126,7 @@ GIT_EXTERN(int) git_reflog_drop(
  * @param entry a reflog entry
  * @return the old oid
  */
-GIT_EXTERN(const git_oid *) git_reflog_entry_oidold(const git_reflog_entry *entry);
+GIT_EXTERN(const git_oid *) git_reflog_entry_id_old(const git_reflog_entry *entry);
 
 /**
  * Get the new oid
@@ -134,7 +134,7 @@ GIT_EXTERN(const git_oid *) git_reflog_entry_oidold(const git_reflog_entry *entr
  * @param entry a reflog entry
  * @return the new oid at this time
  */
-GIT_EXTERN(const git_oid *) git_reflog_entry_oidnew(const git_reflog_entry *entry);
+GIT_EXTERN(const git_oid *) git_reflog_entry_id_new(const git_reflog_entry *entry);
 
 /**
  * Get the committer of this entry
@@ -142,15 +142,15 @@ GIT_EXTERN(const git_oid *) git_reflog_entry_oidnew(const git_reflog_entry *entr
  * @param entry a reflog entry
  * @return the committer
  */
-GIT_EXTERN(git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry);
+GIT_EXTERN(const git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry);
 
 /**
- * Get the log msg
+ * Get the log message
  *
  * @param entry a reflog entry
  * @return the log msg
  */
-GIT_EXTERN(char *) git_reflog_entry_msg(const git_reflog_entry *entry);
+GIT_EXTERN(const char *) git_reflog_entry_message(const git_reflog_entry *entry);
 
 /**
  * Free the reflog
diff --git a/include/git2/refs.h b/include/git2/refs.h
index bc3f44482..4e5a691e6 100644
--- a/include/git2/refs.h
+++ b/include/git2/refs.h
@@ -29,12 +29,12 @@ GIT_BEGIN_DECL
  * See `git_reference_create_symbolic()` for documentation about valid
  * reference names.
  *
- * @param reference_out pointer to the looked-up reference
+ * @param out pointer to the looked-up reference
  * @param repo the repository to look up the reference
  * @param name the long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...)
- * @return 0 or an error code
+ * @return 0 or an error code (ENOTFOUND, EINVALIDSPEC)
  */
-GIT_EXTERN(int) git_reference_lookup(git_reference **reference_out, git_repository *repo, const char *name);
+GIT_EXTERN(int) git_reference_lookup(git_reference **out, git_repository *repo, const char *name);
 
 /**
  * Lookup a reference by name and resolve immediately to OID.
@@ -43,12 +43,13 @@ GIT_EXTERN(int) git_reference_lookup(git_reference **reference_out, git_reposito
  * through to the object id that it refers to.  This avoids having to
  * allocate or free any `git_reference` objects for simple situations.
  *
- * @param oid Pointer to oid to be filled in
+ * @param out Pointer to oid to be filled in
  * @param repo The repository in which to look up the reference
  * @param name The long name for the reference
- * @return 0 on success, -1 if name could not be resolved
+ * @return 0 on success, -1 if name could not be resolved (EINVALIDSPEC,
+ * ENOTFOUND, etc)
  */
-GIT_EXTERN(int) git_reference_name_to_oid(
+GIT_EXTERN(int) git_reference_name_to_id(
 	git_oid *out, git_repository *repo, const char *name);
 
 /**
@@ -73,14 +74,14 @@ GIT_EXTERN(int) git_reference_name_to_oid(
  * This function will return an error if a reference already exists with the
  * given name unless `force` is true, in which case it will be overwritten.
  *
- * @param ref_out Pointer to the newly created reference
+ * @param out Pointer to the newly created reference
  * @param repo Repository where that reference will live
  * @param name The name of the reference
  * @param target The target of the reference
  * @param force Overwrite existing references
- * @return 0 or an error code
+ * @return 0 or an error code (EEXISTS, EINVALIDSPEC)
  */
-GIT_EXTERN(int) git_reference_create_symbolic(git_reference **ref_out, git_repository *repo, const char *name, const char *target, int force);
+GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force);
 
 /**
  * Create a new direct reference.
@@ -105,14 +106,14 @@ GIT_EXTERN(int) git_reference_create_symbolic(git_reference **ref_out, git_repos
  * This function will return an error if a reference already exists with the
  * given name unless `force` is true, in which case it will be overwritten.
  *
- * @param ref_out Pointer to the newly created reference
+ * @param out Pointer to the newly created reference
  * @param repo Repository where that reference will live
  * @param name The name of the reference
  * @param id The object id pointed to by the reference.
  * @param force Overwrite existing references
- * @return 0 or an error code
+ * @return 0 or an error code (EINVALIDSPEC, EEXISTS)
  */
-GIT_EXTERN(int) git_reference_create_oid(git_reference **ref_out, git_repository *repo, const char *name, const git_oid *id, int force);
+GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force);
 
 /**
  * Get the OID pointed to by a direct reference.
@@ -127,7 +128,7 @@ GIT_EXTERN(int) git_reference_create_oid(git_reference **ref_out, git_repository
  * @param ref The reference
  * @return a pointer to the oid if available, NULL otherwise
  */
-GIT_EXTERN(const git_oid *) git_reference_oid(git_reference *ref);
+GIT_EXTERN(const git_oid *) git_reference_target(const git_reference *ref);
 
 /**
  * Get full name to the reference pointed to by a symbolic reference.
@@ -137,7 +138,7 @@ GIT_EXTERN(const git_oid *) git_reference_oid(git_reference *ref);
  * @param ref The reference
  * @return a pointer to the name if available, NULL otherwise
  */
-GIT_EXTERN(const char *) git_reference_target(git_reference *ref);
+GIT_EXTERN(const char *) git_reference_symbolic_target(const git_reference *ref);
 
 /**
  * Get the type of a reference.
@@ -147,7 +148,7 @@ GIT_EXTERN(const char *) git_reference_target(git_reference *ref);
  * @param ref The reference
  * @return the type
  */
-GIT_EXTERN(git_ref_t) git_reference_type(git_reference *ref);
+GIT_EXTERN(git_ref_t) git_reference_type(const git_reference *ref);
 
 /**
  * Get the full name of a reference.
@@ -157,7 +158,7 @@ GIT_EXTERN(git_ref_t) git_reference_type(git_reference *ref);
  * @param ref The reference
  * @return the full name for the ref
  */
-GIT_EXTERN(const char *) git_reference_name(git_reference *ref);
+GIT_EXTERN(const char *) git_reference_name(const git_reference *ref);
 
 /**
  * Resolve a symbolic reference to a direct reference.
@@ -175,7 +176,7 @@ GIT_EXTERN(const char *) git_reference_name(git_reference *ref);
  * @param ref The reference
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_reference_resolve(git_reference **resolved_ref, git_reference *ref);
+GIT_EXTERN(int) git_reference_resolve(git_reference **out, const git_reference *ref);
 
 /**
  * Get the repository where a reference resides.
@@ -183,7 +184,7 @@ GIT_EXTERN(int) git_reference_resolve(git_reference **resolved_ref, git_referenc
  * @param ref The reference
  * @return a pointer to the repo
  */
-GIT_EXTERN(git_repository *) git_reference_owner(git_reference *ref);
+GIT_EXTERN(git_repository *) git_reference_owner(const git_reference *ref);
 
 /**
  * Set the symbolic target of a reference.
@@ -194,9 +195,9 @@ GIT_EXTERN(git_repository *) git_reference_owner(git_reference *ref);
  *
  * @param ref The reference
  * @param target The new target for the reference
- * @return 0 or an error code
+ * @return 0 or an error code (EINVALIDSPEC)
  */
-GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const char *target);
+GIT_EXTERN(int) git_reference_symbolic_set_target(git_reference *ref, const char *target);
 
 /**
  * Set the OID target of a reference.
@@ -209,7 +210,7 @@ GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const char *target)
  * @param id The new target OID for the reference
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id);
+GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const git_oid *id);
 
 /**
  * Rename an existing reference.
@@ -231,12 +232,12 @@ GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id);
  * the reflog if it exists.
  *
  * @param ref The reference to rename
- * @param new_name The new name for the reference
+ * @param name The new name for the reference
  * @param force Overwrite an existing reference
- * @return 0 or an error code
+ * @return 0 or an error code (EINVALIDSPEC, EEXISTS)
  *
  */
-GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, int force);
+GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *name, int force);
 
 /**
  * Delete an existing reference.