Merge pull request #5111 from tiennou/fix/docs

Documentation fixes

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.

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;

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.

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;
 

include/git2/odb.h

@@ -11,6 +11,7 @@
 #include "types.h"
 #include "oid.h"
 #include "oidarray.h"
+#include "indexer.h"
 
 /**
  * @file git2/odb.h

include/git2/odb_backend.h

@@ -9,6 +9,7 @@
 
 #include "common.h"
 #include "types.h"
+#include "indexer.h"
 
 /**
  * @file git2/backend.h

include/git2/pack.h

@@ -9,6 +9,7 @@
 
 #include "common.h"
 #include "oid.h"
+#include "indexer.h"
 
 /**
  * @file git2/pack.h
@@ -178,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);
 
 /**

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);
 
 /**

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

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);
 

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);
 
 /**