refs: conditional wording fixups

This addresses arrbee's concerns about wording in the conditional
reference udpate functions.

1 files changed, 11 insertions, 8 deletions

diff --git a/include/git2/refs.h b/include/git2/refs.h
index 970faf744..478878210 100644
--- a/include/git2/refs.h
+++ b/include/git2/refs.h
@@ -93,8 +93,9 @@ GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, co
  * reference does not belong in the standard set (HEAD, branches and
  * remote-tracking branches) and it does not have a reflog.
  *
- * It will also return an error if the reference's value at the time
- * of updating does not match the one passed.
+ * It will return GIT_EMODIFIED if the reference's value at the time
+ * of updating does not match the one passed through `current_value`
+ * (i.e. if the ref has changed since the user read it).
  *
  * @param out Pointer to the newly created reference
  * @param repo Repository where that reference will live
@@ -103,9 +104,10 @@ GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, co
  * @param force Overwrite existing references
  * @param signature The identity that will used to populate the reflog entry
  * @param log_message The one line long message to be appended to the reflog
+ * @param current_value The expected value of the reference when updating
  * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC, GIT_EMODIFIED or an error code
  */
-GIT_EXTERN(int) git_reference_symbolic_create_matching(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const git_signature *signature, const char *log_message, const char *old_value);
+GIT_EXTERN(int) git_reference_symbolic_create_matching(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const git_signature *signature, const char *log_message, const char *current_value);
 
 /**
  * Create a new symbolic reference.
@@ -210,8 +212,9 @@ GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo,
  * reference does not belong in the standard set (HEAD, branches and
  * remote-tracking branches) and and it does not have a reflog.
  *
- * It will also return an error if the reference's value at the time
- * of updating does not match the one passed.
+ * It will return GIT_EMODIFIED if the reference's value at the time
+ * of updating does not match the one passed through `current_id`
+ * (i.e. if the ref has changed since the user read it).
  *
  * @param out Pointer to the newly created reference
  * @param repo Repository where that reference will live
@@ -221,11 +224,11 @@ GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo,
  * @param force Overwrite existing references
  * @param signature The identity that will used to populate the reflog entry
  * @param log_message The one line long message to be appended to the reflog
- * @param old_id The old value which the reference should have
+ * @param current_id The expected value of the reference at the time of update
  * @return 0 on success, GIT_EMODIFIED if the value of the reference
  * has changed, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
  */
-GIT_EXTERN(int) git_reference_create_matching(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const git_signature *signature, const char *log_message, const git_oid *old_id);
+GIT_EXTERN(int) git_reference_create_matching(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const git_signature *signature, const char *log_message, const git_oid *current_id);
 
 /**
  * Get the OID pointed to by a direct reference.
@@ -350,7 +353,7 @@ GIT_EXTERN(int) git_reference_symbolic_set_target(
  * @param signature The identity that will used to populate the reflog entry
  * @param log_message The one line long message to be appended to the reflog
  * @return 0 on success, GIT_EMODIFIED if the value of the reference
- * has changed, or an error code
+ * has changed since it was read, or an error code
  */
 GIT_EXTERN(int) git_reference_set_target(
 	git_reference **out,