From 764196fffb76b5ddefb378910877c737778cb500 Mon Sep 17 00:00:00 2001 From: Etienne Samson Date: Thu, 13 Jun 2019 20:17:01 +0200 Subject: doc: add missing documentation comments --- include/git2/apply.h | 1 + include/git2/checkout.h | 1 + include/git2/index.h | 1 + include/git2/indexer.h | 5 ++++- include/git2/pack.h | 10 ++++++++++ include/git2/refs.h | 19 +++++++++++++++++++ include/git2/remote.h | 1 + include/git2/repository.h | 21 +++++++++++++++++++++ include/git2/tag.h | 11 ++++++++++- 9 files changed, 68 insertions(+), 2 deletions(-) diff --git a/include/git2/apply.h b/include/git2/apply.h index 384e11718..09d652122 100644 --- a/include/git2/apply.h +++ b/include/git2/apply.h @@ -91,6 +91,7 @@ GIT_EXTERN(int) git_apply_to_tree( git_diff *diff, const git_apply_options *options); +/** Possible application locations for git_apply */ typedef enum { /** * Apply the patch to the workdir, leaving the index untouched. diff --git a/include/git2/checkout.h b/include/git2/checkout.h index 20fa6d647..7b1045599 100644 --- a/include/git2/checkout.h +++ b/include/git2/checkout.h @@ -225,6 +225,7 @@ typedef enum { GIT_CHECKOUT_NOTIFY_ALL = 0x0FFFFu } git_checkout_notify_t; +/** Checkout performance-reporting structure */ typedef struct { size_t mkdir_calls; size_t stat_calls; diff --git a/include/git2/index.h b/include/git2/index.h index 419184cc3..fce361600 100644 --- a/include/git2/index.h +++ b/include/git2/index.h @@ -143,6 +143,7 @@ typedef enum { GIT_INDEX_ADD_CHECK_PATHSPEC = (1u << 2), } git_index_add_option_t; +/** Git index stage states */ typedef enum { /** * Match any index stage. diff --git a/include/git2/indexer.h b/include/git2/indexer.h index 1442f5173..8059e4db3 100644 --- a/include/git2/indexer.h +++ b/include/git2/indexer.h @@ -13,6 +13,7 @@ GIT_BEGIN_DECL +/** A git indexer object */ typedef struct git_indexer git_indexer; /** @@ -55,7 +56,9 @@ typedef struct git_indexer_progress { */ typedef int GIT_CALLBACK(git_indexer_progress_cb)(const git_indexer_progress *stats, void *payload); - +/** + * Options for indexer configuration + */ typedef struct git_indexer_options { unsigned int version; diff --git a/include/git2/pack.h b/include/git2/pack.h index 08d2caff1..922a3cd9d 100644 --- a/include/git2/pack.h +++ b/include/git2/pack.h @@ -179,6 +179,16 @@ GIT_EXTERN(int) git_packbuilder_write( */ GIT_EXTERN(const git_oid *) git_packbuilder_hash(git_packbuilder *pb); +/** + * Callback used to iterate over packed objects + * + * @see git_packbuilder_foreach + * + * @param buf A pointer to the object's data + * @param size The size of the underlying object + * @param payload Payload passed to git_packbuilder_foreach + * @return non-zero to terminate the iteration + */ typedef int GIT_CALLBACK(git_packbuilder_foreach_cb)(void *buf, size_t size, void *payload); /** diff --git a/include/git2/refs.h b/include/git2/refs.h index 8eeab7e92..c9cce2212 100644 --- a/include/git2/refs.h +++ b/include/git2/refs.h @@ -422,7 +422,26 @@ GIT_EXTERN(int) git_reference_remove(git_repository *repo, const char *name); */ GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo); +/** + * Callback used to iterate over references + * + * @see git_reference_foreach + * + * @param reference The reference object + * @param payload Payload passed to git_reference_foreach + * @return non-zero to terminate the iteration + */ typedef int GIT_CALLBACK(git_reference_foreach_cb)(git_reference *reference, void *payload); + +/** + * Callback used to iterate over reference names + * + * @see git_reference_foreach_name + * + * @param name The reference name + * @param payload Payload passed to git_reference_foreach_name + * @return non-zero to terminate the iteration + */ typedef int GIT_CALLBACK(git_reference_foreach_name_cb)(const char *name, void *payload); /** diff --git a/include/git2/remote.h b/include/git2/remote.h index 73c2482ea..4303a06af 100644 --- a/include/git2/remote.h +++ b/include/git2/remote.h @@ -599,6 +599,7 @@ GIT_EXTERN(int) git_remote_init_callbacks( git_remote_callbacks *opts, unsigned int version); +/** Acceptable prune settings when fetching */ typedef enum { /** * Use the setting from the configuration diff --git a/include/git2/repository.h b/include/git2/repository.h index 7d48e9e8d..364e0ea1c 100644 --- a/include/git2/repository.h +++ b/include/git2/repository.h @@ -640,6 +640,18 @@ GIT_EXTERN(int) git_repository_message_remove(git_repository *repo); */ GIT_EXTERN(int) git_repository_state_cleanup(git_repository *repo); +/** + * Callback used to iterate over each FETCH_HEAD entry + * + * @see git_repository_fetchhead_foreach + * + * @param ref_name The reference name + * @param remote_url The remote URL + * @param oid The reference target OID + * @param is_merge Was the reference the result of a merge + * @param payload Payload passed to git_repository_fetchhead_foreach + * @return non-zero to terminate the iteration + */ typedef int GIT_CALLBACK(git_repository_fetchhead_foreach_cb)(const char *ref_name, const char *remote_url, const git_oid *oid, @@ -662,6 +674,15 @@ GIT_EXTERN(int) git_repository_fetchhead_foreach( git_repository_fetchhead_foreach_cb callback, void *payload); +/** + * Callback used to iterate over each MERGE_HEAD entry + * + * @see git_repository_mergehead_foreach + * + * @param oid The merge OID + * @param payload Payload passed to git_repository_mergehead_foreach + * @return non-zero to terminate the iteration + */ typedef int GIT_CALLBACK(git_repository_mergehead_foreach_cb)(const git_oid *oid, void *payload); diff --git a/include/git2/tag.h b/include/git2/tag.h index 1ca334843..c2d490d26 100644 --- a/include/git2/tag.h +++ b/include/git2/tag.h @@ -317,7 +317,16 @@ GIT_EXTERN(int) git_tag_list_match( const char *pattern, git_repository *repo); - +/** + * Callback used to iterate over tag names + * + * @see git_tag_foreach + * + * @param name The tag name + * @param oid The tag's OID + * @param payload Payload passed to git_tag_foreach + * @return non-zero to terminate the iteration + */ typedef int GIT_CALLBACK(git_tag_foreach_cb)(const char *name, git_oid *oid, void *payload); /** -- cgit v1.2.1