undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refs.h: remove duplication in function docstrings

Browse Source 
Add more information to the comment introducing the four reference
transaction update functions, so that each function's docstring
doesn't have to repeat it. Add a pointer from the individual
functions' docstrings to the introductory comment.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Michael Haggerty 2015-02-17 18:00:23 +01:00 committed by Junio C Hamano
parent 4b7b520b9f
commit d1dd721f11
1 changed files with 43 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
refs.h
View File

@ -255,11 +255,31 @@ enum action_on_err {
struct ref_transaction *ref_transaction_begin(struct strbuf *err); struct ref_transaction *ref_transaction_begin(struct strbuf *err);
/* /*
* The following functions add a reference check or update to a * Reference transaction updates
* ref_transaction. In all of them, refname is the name of the *
* reference to be affected. The functions make internal copies of * The following four functions add a reference check or update to a
* refname and msg, so the caller retains ownership of these parameters. * ref_transaction. They have some common similar parameters:
* flags can be REF_NODEREF; it is passed to update_ref_lock(). *
* transaction -- a pointer to an open ref_transaction, obtained
* from ref_transaction_begin().
*
* refname -- the name of the reference to be affected.
*
* flags -- flags affecting the update, passed to
* update_ref_lock(). Can be REF_NODEREF, which means that
* symbolic references should not be followed.
*
* msg -- a message describing the change (for the reflog).
*
* err -- a strbuf for receiving a description of any error that
* might have occured.
*
* The functions make internal copies of refname and msg, so the
* caller retains ownership of these parameters.
*
* The functions return 0 on success and non-zero on failure. A
* failure means that the transaction as a whole has failed and needs
* to be rolled back.
*/ */
/* /*
@ -273,9 +293,8 @@ struct ref_transaction *ref_transaction_begin(struct strbuf *err);
* whole transaction fails. If old_sha1 is NULL, then the previous * whole transaction fails. If old_sha1 is NULL, then the previous
* value is not checked. * value is not checked.
* *
* Return 0 on success and non-zero on failure. Any failure in the * See the above comment "Reference transaction updates" for more
* transaction means that the transaction as a whole has failed and * information.
* will need to be rolled back.
*/ */
int ref_transaction_update(struct ref_transaction *transaction, int ref_transaction_update(struct ref_transaction *transaction,
const char *refname, const char *refname,
@ -285,13 +304,13 @@ int ref_transaction_update(struct ref_transaction *transaction,
struct strbuf *err); struct strbuf *err);
/* /*
* Add a reference creation to transaction. new_sha1 is the value * Add a reference creation to transaction. new_sha1 is the value that
* that the reference should have after the update; it must not be the * the reference should have after the update; it must not be
* null SHA-1. It is verified that the reference does not exist * null_sha1. It is verified that the reference does not exist
* already. * already.
* Function returns 0 on success and non-zero on failure. A failure to create *
* means that the transaction as a whole has failed and will need to be * See the above comment "Reference transaction updates" for more
* rolled back. * information.
*/ */
int ref_transaction_create(struct ref_transaction *transaction, int ref_transaction_create(struct ref_transaction *transaction,
const char *refname, const char *refname,
@ -300,12 +319,12 @@ int ref_transaction_create(struct ref_transaction *transaction,
struct strbuf *err); struct strbuf *err);
/* /*
* Add a reference deletion to transaction. If old_sha1 is non-NULL, then * Add a reference deletion to transaction. If old_sha1 is non-NULL,
* it holds the value that the reference should have had before * then it holds the value that the reference should have had before
* the update (which must not be the null SHA-1). * the update (which must not be null_sha1).
* Function returns 0 on success and non-zero on failure. A failure to delete *
* means that the transaction as a whole has failed and will need to be * See the above comment "Reference transaction updates" for more
* rolled back. * information.
*/ */
int ref_transaction_delete(struct ref_transaction *transaction, int ref_transaction_delete(struct ref_transaction *transaction,
const char *refname, const char *refname,
@ -316,9 +335,10 @@ int ref_transaction_delete(struct ref_transaction *transaction,
/* /*
* Verify, within a transaction, that refname has the value old_sha1, * Verify, within a transaction, that refname has the value old_sha1,
* or, if old_sha1 is null_sha1, then verify that the reference * or, if old_sha1 is null_sha1, then verify that the reference
* doesn't exist. old_sha1 must be non-NULL. Function returns 0 on * doesn't exist. old_sha1 must be non-NULL.
* success and non-zero on failure. A failure to verify means that the *
* transaction as a whole has failed and will need to be rolled back. * See the above comment "Reference transaction updates" for more
* information.
*/ */
int ref_transaction_verify(struct ref_transaction *transaction, int ref_transaction_verify(struct ref_transaction *transaction,
const char *refname, const char *refname,