refs.h: remove duplication in function docstrings
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>
Michael Haggerty committed
Feb 17, 2015 at 18:00 UTC
d1dd721f11b7b124f35e347876e5d7204a3df664
1 file changed
+43
-23
refs.h
+43
-23
@@ -255,11 +255,31 @@ enum action_on_err {
255
struct ref_transaction *ref_transaction_begin(struct strbuf *err);
256
257
/*
258
- * The following functions add a reference check or update to a
259
- * ref_transaction. In all of them, refname is the name of the
260
- * reference to be affected. The functions make internal copies of
261
- * refname and msg, so the caller retains ownership of these parameters.
262
- * flags can be REF_NODEREF; it is passed to update_ref_lock().
258
+ * Reference transaction updates
259
+ *
260
+ * The following four functions add a reference check or update to a
261
+ * ref_transaction. They have some common similar parameters:
262
+ *
263
+ * transaction -- a pointer to an open ref_transaction, obtained
264
+ * from ref_transaction_begin().
265
+ *
266
+ * refname -- the name of the reference to be affected.
267
+ *
268
+ * flags -- flags affecting the update, passed to
269
+ * update_ref_lock(). Can be REF_NODEREF, which means that
270
+ * symbolic references should not be followed.
271
+ *
272
+ * msg -- a message describing the change (for the reflog).
273
+ *
274
+ * err -- a strbuf for receiving a description of any error that
275
+ * might have occured.
276
+ *
277
+ * The functions make internal copies of refname and msg, so the
278
+ * caller retains ownership of these parameters.
279
+ *
280
+ * The functions return 0 on success and non-zero on failure. A
281
+ * failure means that the transaction as a whole has failed and needs
282
+ * to be rolled back.
283
*/
284
285
/*
@@ -273,9 +293,8 @@ struct ref_transaction *ref_transaction_begin(struct strbuf *err);
293
* whole transaction fails. If old_sha1 is NULL, then the previous
294
* value is not checked.
295
*
276
- * Return 0 on success and non-zero on failure. Any failure in the
277
- * transaction means that the transaction as a whole has failed and
278
- * will need to be rolled back.
296
+ * See the above comment "Reference transaction updates" for more
297
+ * information.
298
*/
299
int ref_transaction_update(struct ref_transaction *transaction,
300
const char *refname,
@@ -285,13 +304,13 @@ int ref_transaction_update(struct ref_transaction *transaction,
304
struct strbuf *err);
305
306
/*
288
- * Add a reference creation to transaction. new_sha1 is the value
289
- * that the reference should have after the update; it must not be the
290
- * null SHA-1. It is verified that the reference does not exist
307
+ * Add a reference creation to transaction. new_sha1 is the value that
308
+ * the reference should have after the update; it must not be
309
+ * null_sha1. It is verified that the reference does not exist
310
* already.
292
- * Function returns 0 on success and non-zero on failure. A failure to create
293
- * means that the transaction as a whole has failed and will need to be
294
- * rolled back.
311
+ *
312
+ * See the above comment "Reference transaction updates" for more
313
+ * information.
314
*/
315
int ref_transaction_create(struct ref_transaction *transaction,
316
const char *refname,
@@ -300,12 +319,12 @@ int ref_transaction_create(struct ref_transaction *transaction,
319
struct strbuf *err);
320
321
/*
303
- * Add a reference deletion to transaction. If old_sha1 is non-NULL, then
304
- * it holds the value that the reference should have had before
305
- * the update (which must not be the null SHA-1).
306
- * Function returns 0 on success and non-zero on failure. A failure to delete
307
- * means that the transaction as a whole has failed and will need to be
308
- * rolled back.
322
+ * Add a reference deletion to transaction. If old_sha1 is non-NULL,
323
+ * then it holds the value that the reference should have had before
324
+ * the update (which must not be null_sha1).
325
+ *
326
+ * See the above comment "Reference transaction updates" for more
327
+ * information.
328
*/
329
int ref_transaction_delete(struct ref_transaction *transaction,
330
const char *refname,
@@ -316,9 +335,10 @@ int ref_transaction_delete(struct ref_transaction *transaction,
335
/*
336
* Verify, within a transaction, that refname has the value old_sha1,
337
* or, if old_sha1 is null_sha1, then verify that the reference
319
- * doesn't exist. old_sha1 must be non-NULL. Function returns 0 on
320
- * success and non-zero on failure. A failure to verify means that the
321
- * transaction as a whole has failed and will need to be rolled back.
338
+ * doesn't exist. old_sha1 must be non-NULL.
339
+ *
340
+ * See the above comment "Reference transaction updates" for more
341
+ * information.
342
*/
343
int ref_transaction_verify(struct ref_transaction *transaction,
344
const char *refname,