Commit 764196fffb76b5ddefb378910877c737778cb500

Etienne Samson 2019-06-13T20:17:01

doc: add missing documentation comments

diff --git a/include/git2/apply.h b/include/git2/apply.h
index 384e117..09d6521 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 20fa6d6..7b10455 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 419184c..fce3616 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 1442f51..8059e4d 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 08d2caf..922a3cd 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 8eeab7e..c9cce22 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 73c2482..4303a06 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 7d48e9e..364e0ea 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 1ca3348..c2d490d 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);
 
 /**