On Thu, Mar 20, 2025 at 12:44:00PM +0100, Karthik Nayak wrote:
> diff --git a/refs.h b/refs.h
> index 240e2d8537..dcd83e81e2 100644
> --- a/refs.h
> +++ b/refs.h
> @@ -16,6 +16,29 @@ struct worktree;
> enum ref_storage_format ref_storage_format_by_name(const char *name);
> const char *ref_storage_format_to_name(enum ref_storage_format ref_storage_format);
>
> +/*
> + * enum ref_transaction_error represents the following return codes:
> + * REF_TRANSACTION_ERROR_GENERIC error_code: default error code.
> + * REF_TRANSACTION_ERROR_NAME_CONFLICT error_code: ref name conflict like A vs A/B.
> + * REF_TRANSACTION_ERROR_CREATE_EXISTS error_code: ref to be created already exists.
> + * REF_TRANSACTION_ERROR_NONEXISTENT_REF error_code: ref expected but doesn't exist.
> + * REF_TRANSACTION_ERROR_INCORRECT_OLD_VALUE error_code: provided old_oid or old_target of
> + * reference doesn't match actual.
> + * REF_TRANSACTION_ERROR_INVALID_NEW_VALUE error_code: provided new_oid or new_target is
> + * invalid.
> + * REF_TRANSACTION_ERROR_EXPECTED_SYMREF error_code: expected ref to be symref, but is a
> + * regular ref.
> + */
> +enum ref_transaction_error {
> + REF_TRANSACTION_ERROR_GENERIC = -1,
> + REF_TRANSACTION_ERROR_NAME_CONFLICT = -2,
> + REF_TRANSACTION_ERROR_CREATE_EXISTS = -3,
> + REF_TRANSACTION_ERROR_NONEXISTENT_REF = -4,
> + REF_TRANSACTION_ERROR_INCORRECT_OLD_VALUE = -5,
> + REF_TRANSACTION_ERROR_INVALID_NEW_VALUE = -6,
> + REF_TRANSACTION_ERROR_EXPECTED_SYMREF = -7,
> +};
> +
Tiny nit: I think it's generally preferable to document each specific
right next to its definition.
Patrick
