rugged 1.3.1 → 1.9.0

data/vendor/libgit2/include/git2/deprecated.h

@@ -52,7 +52,7 @@
 
 /**
  * @file git2/deprecated.h
- * @brief libgit2 deprecated functions and values
+ * @brief Deprecated functions and values
  * @ingroup Git
  * @{
  */
@@ -69,15 +69,23 @@ GIT_BEGIN_DECL
  */
 /**@{*/
 
+/** @deprecated use GIT_ATTR_VALUE_UNSPECIFIED */
 #define GIT_ATTR_UNSPECIFIED_T GIT_ATTR_VALUE_UNSPECIFIED
+/** @deprecated use GIT_ATTR_VALUE_TRUE */
 #define GIT_ATTR_TRUE_T GIT_ATTR_VALUE_TRUE
+/** @deprecated use GIT_ATTR_VALUE_FALSE */
 #define GIT_ATTR_FALSE_T GIT_ATTR_VALUE_FALSE
+/** @deprecated use GIT_ATTR_VALUE_STRING */
 #define GIT_ATTR_VALUE_T GIT_ATTR_VALUE_STRING
 
+/** @deprecated use GIT_ATTR_IS_TRUE */
 #define GIT_ATTR_TRUE(attr) GIT_ATTR_IS_TRUE(attr)
+/** @deprecated use GIT_ATTR_IS_FALSE */
 #define GIT_ATTR_FALSE(attr) GIT_ATTR_IS_FALSE(attr)
+/** @deprecated use GIT_ATTR_IS_UNSPECIFIED */
 #define GIT_ATTR_UNSPECIFIED(attr) GIT_ATTR_IS_UNSPECIFIED(attr)
 
+/** @deprecated use git_attr_value_t */
 typedef git_attr_value_t git_attr_t;
 
 /**@}*/
@@ -93,6 +101,7 @@ typedef git_attr_value_t git_attr_t;
  */
 /**@{*/
 
+/** @deprecated use GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD */
 #define GIT_BLOB_FILTER_ATTTRIBUTES_FROM_HEAD GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD
 
 GIT_EXTERN(int) git_blob_create_fromworkdir(git_oid *id, git_repository *repo, const char *relative_path);
@@ -285,11 +294,16 @@ typedef int (*git_commit_signing_cb)(
  */
 /**@{*/
 
+/** @deprecated use GIT_CONFIGMAP_FALSE */
 #define GIT_CVAR_FALSE  GIT_CONFIGMAP_FALSE
+/** @deprecated use GIT_CONFIGMAP_TRUE */
 #define GIT_CVAR_TRUE   GIT_CONFIGMAP_TRUE
+/** @deprecated use GIT_CONFIGMAP_INT32 */
 #define GIT_CVAR_INT32  GIT_CONFIGMAP_INT32
+/** @deprecated use GIT_CONFIGMAP_STRING */
 #define GIT_CVAR_STRING GIT_CONFIGMAP_STRING
 
+/** @deprecated use git_cvar_map */
 typedef git_configmap git_cvar_map;
 
 /**@}*/
@@ -313,12 +327,13 @@ typedef enum {
 	GIT_DIFF_FORMAT_EMAIL_NONE = 0,
 
 	/** Don't insert "[PATCH]" in the subject header*/
-	GIT_DIFF_FORMAT_EMAIL_EXCLUDE_SUBJECT_PATCH_MARKER = (1 << 0),
-
+	GIT_DIFF_FORMAT_EMAIL_EXCLUDE_SUBJECT_PATCH_MARKER = (1 << 0)
 } git_diff_format_email_flags_t;
 
 /**
  * Options for controlling the formatting of the generated e-mail.
+ *
+ * @deprecated use `git_email_create_options`
  */
 typedef struct {
 	unsigned int version;
@@ -345,7 +360,9 @@ typedef struct {
 	const git_signature *author;
 } git_diff_format_email_options;
 
+/** @deprecated use `git_email_create_options` */
 #define GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION 1
+/** @deprecated use `git_email_create_options` */
 #define GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT {GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION, 0, 1, 1, NULL, NULL, NULL, NULL}
 
 /**
@@ -401,40 +418,76 @@ GIT_EXTERN(int) git_diff_format_email_options_init(
  */
 /**@{*/
 
+/** @deprecated use `GIT_ERROR_NONE` */
 #define GITERR_NONE GIT_ERROR_NONE
+/** @deprecated use `GIT_ERROR_NOMEMORY` */
 #define GITERR_NOMEMORY GIT_ERROR_NOMEMORY
+/** @deprecated use `GIT_ERROR_OS` */
 #define GITERR_OS GIT_ERROR_OS
+/** @deprecated use `GIT_ERROR_INVALID` */
 #define GITERR_INVALID GIT_ERROR_INVALID
+/** @deprecated use `GIT_ERROR_REFERENCE` */
 #define GITERR_REFERENCE GIT_ERROR_REFERENCE
+/** @deprecated use `GIT_ERROR_ZLIB` */
 #define GITERR_ZLIB GIT_ERROR_ZLIB
+/** @deprecated use `GIT_ERROR_REPOSITORY` */
 #define GITERR_REPOSITORY GIT_ERROR_REPOSITORY
+/** @deprecated use `GIT_ERROR_CONFIG` */
 #define GITERR_CONFIG GIT_ERROR_CONFIG
+/** @deprecated use `GIT_ERROR_REGEX` */
 #define GITERR_REGEX GIT_ERROR_REGEX
+/** @deprecated use `GIT_ERROR_ODB` */
 #define GITERR_ODB GIT_ERROR_ODB
+/** @deprecated use `GIT_ERROR_INDEX` */
 #define GITERR_INDEX GIT_ERROR_INDEX
+/** @deprecated use `GIT_ERROR_OBJECT` */
 #define GITERR_OBJECT GIT_ERROR_OBJECT
+/** @deprecated use `GIT_ERROR_NET` */
 #define GITERR_NET GIT_ERROR_NET
+/** @deprecated use `GIT_ERROR_TAG` */
 #define GITERR_TAG GIT_ERROR_TAG
+/** @deprecated use `GIT_ERROR_TREE` */
 #define GITERR_TREE GIT_ERROR_TREE
+/** @deprecated use `GIT_ERROR_INDEXER` */
 #define GITERR_INDEXER GIT_ERROR_INDEXER
+/** @deprecated use `GIT_ERROR_SSL` */
 #define GITERR_SSL GIT_ERROR_SSL
+/** @deprecated use `GIT_ERROR_SUBMODULE` */
 #define GITERR_SUBMODULE GIT_ERROR_SUBMODULE
+/** @deprecated use `GIT_ERROR_THREAD` */
 #define GITERR_THREAD GIT_ERROR_THREAD
+/** @deprecated use `GIT_ERROR_STASH` */
 #define GITERR_STASH GIT_ERROR_STASH
+/** @deprecated use `GIT_ERROR_CHECKOUT` */
 #define GITERR_CHECKOUT GIT_ERROR_CHECKOUT
+/** @deprecated use `GIT_ERROR_FETCHHEAD` */
 #define GITERR_FETCHHEAD GIT_ERROR_FETCHHEAD
+/** @deprecated use `GIT_ERROR_MERGE` */
 #define GITERR_MERGE GIT_ERROR_MERGE
+/** @deprecated use `GIT_ERROR_SSH` */
 #define GITERR_SSH GIT_ERROR_SSH
+/** @deprecated use `GIT_ERROR_FILTER` */
 #define GITERR_FILTER GIT_ERROR_FILTER
+/** @deprecated use `GIT_ERROR_REVERT` */
 #define GITERR_REVERT GIT_ERROR_REVERT
+/** @deprecated use `GIT_ERROR_CALLBACK` */
 #define GITERR_CALLBACK GIT_ERROR_CALLBACK
+/** @deprecated use `GIT_ERROR_CHERRYPICK` */
 #define GITERR_CHERRYPICK GIT_ERROR_CHERRYPICK
+/** @deprecated use `GIT_ERROR_DESCRIBE` */
 #define GITERR_DESCRIBE GIT_ERROR_DESCRIBE
+/** @deprecated use `GIT_ERROR_REBASE` */
 #define GITERR_REBASE GIT_ERROR_REBASE
+/** @deprecated use `GIT_ERROR_FILESYSTEM` */
 #define GITERR_FILESYSTEM GIT_ERROR_FILESYSTEM
+/** @deprecated use `GIT_ERROR_PATCH` */
 #define GITERR_PATCH GIT_ERROR_PATCH
+/** @deprecated use `GIT_ERROR_WORKTREE` */
 #define GITERR_WORKTREE GIT_ERROR_WORKTREE
+/** @deprecated use `GIT_ERROR_SHA1` */
 #define GITERR_SHA1 GIT_ERROR_SHA1
+/** @deprecated use `GIT_ERROR_SHA` */
+#define GIT_ERROR_SHA1 GIT_ERROR_SHA
 
 /**
  * Return the last `git_error` object that was generated for the
@@ -498,37 +551,63 @@ GIT_EXTERN(void) giterr_set_oom(void);
  */
 /**@{*/
 
+/* The git_idxentry_extended_flag_t enum */
+/** @deprecated use `GIT_INDEX_ENTRY_NAMEMASK` */
 #define GIT_IDXENTRY_NAMEMASK          GIT_INDEX_ENTRY_NAMEMASK
+/** @deprecated use `GIT_INDEX_ENTRY_STAGEMASK` */
 #define GIT_IDXENTRY_STAGEMASK         GIT_INDEX_ENTRY_STAGEMASK
+/** @deprecated use `GIT_INDEX_ENTRY_STAGESHIFT` */
 #define GIT_IDXENTRY_STAGESHIFT        GIT_INDEX_ENTRY_STAGESHIFT
 
 /* The git_indxentry_flag_t enum */
+/** @deprecated use `GIT_INDEX_ENTRY_EXTENDED` */
 #define GIT_IDXENTRY_EXTENDED          GIT_INDEX_ENTRY_EXTENDED
+/** @deprecated use `GIT_INDEX_ENTRY_VALID` */
 #define GIT_IDXENTRY_VALID             GIT_INDEX_ENTRY_VALID
 
+/** @deprecated use `GIT_INDEX_ENTRY_STAGE` */
 #define GIT_IDXENTRY_STAGE(E)          GIT_INDEX_ENTRY_STAGE(E)
+/** @deprecated use `GIT_INDEX_ENTRY_STAGE_SET` */
 #define GIT_IDXENTRY_STAGE_SET(E,S)    GIT_INDEX_ENTRY_STAGE_SET(E,S)
 
 /* The git_idxentry_extended_flag_t enum */
+/** @deprecated use `GIT_INDEX_ENTRY_INTENT_TO_ADD` */
 #define GIT_IDXENTRY_INTENT_TO_ADD     GIT_INDEX_ENTRY_INTENT_TO_ADD
+/** @deprecated use `GIT_INDEX_ENTRY_SKIP_WORKTREE` */
 #define GIT_IDXENTRY_SKIP_WORKTREE     GIT_INDEX_ENTRY_SKIP_WORKTREE
+/** @deprecated use `GIT_INDEX_ENTRY_INTENT_TO_ADD | GIT_INDEX_ENTRY_SKIP_WORKTREE` */
 #define GIT_IDXENTRY_EXTENDED_FLAGS    (GIT_INDEX_ENTRY_INTENT_TO_ADD | GIT_INDEX_ENTRY_SKIP_WORKTREE)
+/** @deprecated this value is not public */
 #define GIT_IDXENTRY_EXTENDED2         (1 << 15)
+/** @deprecated this value is not public */
 #define GIT_IDXENTRY_UPDATE            (1 << 0)
+/** @deprecated this value is not public */
 #define GIT_IDXENTRY_REMOVE            (1 << 1)
+/** @deprecated this value is not public */
 #define GIT_IDXENTRY_UPTODATE          (1 << 2)
+/** @deprecated this value is not public */
 #define GIT_IDXENTRY_ADDED             (1 << 3)
+/** @deprecated this value is not public */
 #define GIT_IDXENTRY_HASHED            (1 << 4)
+/** @deprecated this value is not public */
 #define GIT_IDXENTRY_UNHASHED          (1 << 5)
+/** @deprecated this value is not public */
 #define GIT_IDXENTRY_WT_REMOVE         (1 << 6)
+/** @deprecated this value is not public */
 #define GIT_IDXENTRY_CONFLICTED        (1 << 7)
+/** @deprecated this value is not public */
 #define GIT_IDXENTRY_UNPACKED          (1 << 8)
+/** @deprecated this value is not public */
 #define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9)
 
 /* The git_index_capability_t enum */
+/** @deprecated use `GIT_INDEX_CAPABILITY_IGNORE_CASE` */
 #define GIT_INDEXCAP_IGNORE_CASE       GIT_INDEX_CAPABILITY_IGNORE_CASE
+/** @deprecated use `GIT_INDEX_CAPABILITY_NO_FILEMODE` */
 #define GIT_INDEXCAP_NO_FILEMODE       GIT_INDEX_CAPABILITY_NO_FILEMODE
+/** @deprecated use `GIT_INDEX_CAPABILITY_NO_SYMLINKS` */
 #define GIT_INDEXCAP_NO_SYMLINKS       GIT_INDEX_CAPABILITY_NO_SYMLINKS
+/** @deprecated use `GIT_INDEX_CAPABILITY_FROM_OWNER` */
 #define GIT_INDEXCAP_FROM_OWNER        GIT_INDEX_CAPABILITY_FROM_OWNER
 
 GIT_EXTERN(int) git_index_add_frombuffer(
@@ -548,17 +627,28 @@ GIT_EXTERN(int) git_index_add_frombuffer(
  */
 /**@{*/
 
+/** @deprecate use `git_object_t` */
 #define git_otype git_object_t
 
+/** @deprecate use `GIT_OBJECT_ANY` */
 #define GIT_OBJ_ANY GIT_OBJECT_ANY
+/** @deprecate use `GIT_OBJECT_INVALID` */
 #define GIT_OBJ_BAD GIT_OBJECT_INVALID
+/** @deprecated this value is not public */
 #define GIT_OBJ__EXT1 0
+/** @deprecate use `GIT_OBJECT_COMMIT` */
 #define GIT_OBJ_COMMIT GIT_OBJECT_COMMIT
+/** @deprecate use `GIT_OBJECT_TREE` */
 #define GIT_OBJ_TREE GIT_OBJECT_TREE
+/** @deprecate use `GIT_OBJECT_BLOB` */
 #define GIT_OBJ_BLOB GIT_OBJECT_BLOB
+/** @deprecate use `GIT_OBJECT_TAG` */
 #define GIT_OBJ_TAG GIT_OBJECT_TAG
+/** @deprecated this value is not public */
 #define GIT_OBJ__EXT2 5
+/** @deprecate use `GIT_OBJECT_OFS_DELTA` */
 #define GIT_OBJ_OFS_DELTA GIT_OBJECT_OFS_DELTA
+/** @deprecate use `GIT_OBJECT_REF_DELTA` */
 #define GIT_OBJ_REF_DELTA GIT_OBJECT_REF_DELTA
 
 /**
@@ -610,17 +700,27 @@ GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name);
 /**@{*/
 
  /** Basic type of any Git reference. */
+/** @deprecate use `git_reference_t` */
 #define git_ref_t git_reference_t
+/** @deprecate use `git_reference_format_t` */
 #define git_reference_normalize_t git_reference_format_t
 
+/** @deprecate use `GIT_REFERENCE_INVALID` */
 #define GIT_REF_INVALID GIT_REFERENCE_INVALID
+/** @deprecate use `GIT_REFERENCE_DIRECT` */
 #define GIT_REF_OID GIT_REFERENCE_DIRECT
+/** @deprecate use `GIT_REFERENCE_SYMBOLIC` */
 #define GIT_REF_SYMBOLIC GIT_REFERENCE_SYMBOLIC
+/** @deprecate use `GIT_REFERENCE_ALL` */
 #define GIT_REF_LISTALL GIT_REFERENCE_ALL
 
+/** @deprecate use `GIT_REFERENCE_FORMAT_NORMAL` */
 #define GIT_REF_FORMAT_NORMAL GIT_REFERENCE_FORMAT_NORMAL
+/** @deprecate use `GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL` */
 #define GIT_REF_FORMAT_ALLOW_ONELEVEL GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL
+/** @deprecate use `GIT_REFERENCE_FORMAT_REFSPEC_PATTERN` */
 #define GIT_REF_FORMAT_REFSPEC_PATTERN GIT_REFERENCE_FORMAT_REFSPEC_PATTERN
+/** @deprecate use `GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND` */
 #define GIT_REF_FORMAT_REFSPEC_SHORTHAND GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND
 
 /**
@@ -661,8 +761,11 @@ GIT_EXTERN(int) git_tag_create_frombuffer(
 
 typedef git_revspec_t git_revparse_mode_t;
 
+/** @deprecated use `GIT_REVSPEC_SINGLE` */
 #define GIT_REVPARSE_SINGLE GIT_REVSPEC_SINGLE
+/** @deprecated use `GIT_REVSPEC_RANGE` */
 #define GIT_REVPARSE_RANGE GIT_REVSPEC_RANGE
+/** @deprecated use `GIT_REVSPEC_MERGE_BASE` */
 #define GIT_REVPARSE_MERGE_BASE GIT_REVSPEC_MERGE_BASE
 
 /**@}*/
@@ -691,14 +794,22 @@ typedef git_credential_sign_cb git_cred_sign_cb;
 typedef git_credential_ssh_interactive_cb git_cred_ssh_interactive_callback;
 typedef git_credential_ssh_interactive_cb git_cred_ssh_interactive_cb;
 
+/** @deprecated use `git_credential_t` */
 #define git_credtype_t git_credential_t
 
+/** @deprecated use `GIT_CREDENTIAL_USERPASS_PLAINTEXT` */
 #define GIT_CREDTYPE_USERPASS_PLAINTEXT GIT_CREDENTIAL_USERPASS_PLAINTEXT
+/** @deprecated use `GIT_CREDENTIAL_SSH_KEY` */
 #define GIT_CREDTYPE_SSH_KEY GIT_CREDENTIAL_SSH_KEY
+/** @deprecated use `GIT_CREDENTIAL_SSH_CUSTOM` */
 #define GIT_CREDTYPE_SSH_CUSTOM GIT_CREDENTIAL_SSH_CUSTOM
+/** @deprecated use `GIT_CREDENTIAL_DEFAULT` */
 #define GIT_CREDTYPE_DEFAULT GIT_CREDENTIAL_DEFAULT
+/** @deprecated use `GIT_CREDENTIAL_SSH_INTERACTIVE` */
 #define GIT_CREDTYPE_SSH_INTERACTIVE GIT_CREDENTIAL_SSH_INTERACTIVE
+/** @deprecated use `GIT_CREDENTIAL_USERNAME` */
 #define GIT_CREDTYPE_USERNAME GIT_CREDENTIAL_USERNAME
+/** @deprecated use `GIT_CREDENTIAL_SSH_MEMORY` */
 #define GIT_CREDTYPE_SSH_MEMORY GIT_CREDENTIAL_SSH_MEMORY
 
 GIT_EXTERN(void) git_cred_free(git_credential *cred);
@@ -775,6 +886,15 @@ typedef git_trace_cb git_trace_callback;
  */
 /**@{*/
 
+#ifndef GIT_EXPERIMENTAL_SHA256
+/** Deprecated OID "raw size" definition */
+# define GIT_OID_RAWSZ    GIT_OID_SHA1_SIZE
+/** Deprecated OID "hex size" definition */
+# define GIT_OID_HEXSZ    GIT_OID_SHA1_HEXSIZE
+/** Deprecated OID "hex zero" definition */
+# define GIT_OID_HEX_ZERO GIT_OID_SHA1_HEXZERO
+#endif
+
 GIT_EXTERN(int) git_oid_iszero(const git_oid *id);
 
 /**@}*/
@@ -884,6 +1004,24 @@ GIT_EXTERN(void) git_strarray_free(git_strarray *array);
 
 /**@}*/
 
+/** @name Deprecated Version Constants
+ *
+ * These constants are retained for backward compatibility.  The newer
+ * versions of these constants should be preferred in all new code.
+ *
+ * There is no plan to remove these backward compatibility constants at
+ * this time.
+ */
+/**@{*/
+
+#define LIBGIT2_VER_MAJOR      LIBGIT2_VERSION_MAJOR
+#define LIBGIT2_VER_MINOR      LIBGIT2_VERSION_MINOR
+#define LIBGIT2_VER_REVISION   LIBGIT2_VERSION_REVISION
+#define LIBGIT2_VER_PATCH      LIBGIT2_VERSION_PATCH
+#define LIBGIT2_VER_PRERELEASE LIBGIT2_VERSION_PRERELEASE
+
+/**@}*/
+
 /** @name Deprecated Options Initialization Functions
  *
  * These functions are retained for backward compatibility.  The newer

data/vendor/libgit2/include/git2/describe.h

@@ -13,10 +13,14 @@
 
 /**
  * @file git2/describe.h
- * @brief Git describing routines
+ * @brief Describe a commit in reference to tags
  * @defgroup git_describe Git describing routines
  * @ingroup Git
  * @{
+ *
+ * Describe a commit, showing information about how the current commit
+ * relates to the tags. This can be useful for showing how the current
+ * commit has changed from a particular tagged version of the repository.
  */
 GIT_BEGIN_DECL
 
@@ -30,7 +34,7 @@ GIT_BEGIN_DECL
 typedef enum {
 	GIT_DESCRIBE_DEFAULT,
 	GIT_DESCRIBE_TAGS,
-	GIT_DESCRIBE_ALL,
+	GIT_DESCRIBE_ALL
 } git_describe_strategy_t;
 
 /**
@@ -60,10 +64,15 @@ typedef struct git_describe_options {
 	int show_commit_oid_as_fallback;
 } git_describe_options;
 
+/** Default maximum candidate tags */
 #define GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS 10
+/** Default abbreviated size */
 #define GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE 7
 
+/** Current version for the `git_describe_options` structure */
 #define GIT_DESCRIBE_OPTIONS_VERSION 1
+
+/** Static constructor for `git_describe_options` */
 #define GIT_DESCRIBE_OPTIONS_INIT { \
 	GIT_DESCRIBE_OPTIONS_VERSION, \
 	GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \
@@ -110,7 +119,10 @@ typedef struct {
 	const char *dirty_suffix;
 } git_describe_format_options;
 
+/** Current version for the `git_describe_format_options` structure */
 #define GIT_DESCRIBE_FORMAT_OPTIONS_VERSION 1
+
+/** Static constructor for `git_describe_format_options` */
 #define GIT_DESCRIBE_FORMAT_OPTIONS_INIT { \
 		GIT_DESCRIBE_FORMAT_OPTIONS_VERSION,   \
 		GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \
@@ -142,6 +154,7 @@ typedef struct git_describe_result git_describe_result;
  * you're done with it.
  * @param committish a committish to describe
  * @param opts the lookup options (or NULL for defaults)
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_describe_commit(
 	git_describe_result **result,
@@ -152,13 +165,14 @@ GIT_EXTERN(int) git_describe_commit(
  * Describe a commit
  *
  * Perform the describe operation on the current commit and the
- * worktree. After peforming describe on HEAD, a status is run and the
+ * worktree. After performing describe on HEAD, a status is run and the
  * description is considered to be dirty if there are.
  *
  * @param out pointer to store the result. You must free this once
  * you're done with it.
  * @param repo the repository in which to perform the describe
  * @param opts the lookup options (or NULL for defaults)
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_describe_workdir(
 	git_describe_result **out,
@@ -172,6 +186,7 @@ GIT_EXTERN(int) git_describe_workdir(
  * @param result the result from `git_describe_commit()` or
  * `git_describe_workdir()`.
  * @param opts the formatting options (or NULL for defaults)
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_describe_format(
 	git_buf *out,
@@ -180,6 +195,8 @@ GIT_EXTERN(int) git_describe_format(
 
 /**
  * Free the describe result.
+ *
+ * @param result The result to free.
  */
 GIT_EXTERN(void) git_describe_result_free(git_describe_result *result);