Merge pull request #4530 from tiennou/fix/docurium-missing-includes

Fix docurium missing includes

24 files changed, 275 insertions, 168 deletions

diff --git a/api.docurium b/api.docurium
index 9e17817db..bf733273b 100644
--- a/api.docurium
+++ b/api.docurium
@@ -1,7 +1,7 @@
 {
  "name":   "libgit2",
  "github": "libgit2/libgit2",
- "input":  "include/git2",
+ "input":  "include",
  "prefix": "git_",
  "output": "docs",
  "branch": "gh-pages",
diff --git a/include/git2/attr.h b/include/git2/attr.h
index 0238f3dd7..651454abc 100644
--- a/include/git2/attr.h
+++ b/include/git2/attr.h
@@ -186,6 +186,22 @@ GIT_EXTERN(int) git_attr_get_many(
 	size_t num_attr,
 	const char **names);
 
+/**
+ * The callback used with git_attr_foreach.
+ *
+ * This callback will be invoked only once per attribute name, even if there
+ * are multiple rules for a given file. The highest priority rule will be
+ * used.
+ *
+ * @see git_attr_foreach.
+ *
+ * @param name The attribute name.
+ * @param value The attribute value. May be NULL if the attribute is explicitly
+ *              set to UNSPECIFIED using the '!' sign.
+ * @param payload A user-specified pointer.
+ * @return 0 to continue looping, non-zero to stop. This value will be returned
+ *         from git_attr_foreach.
+ */
 typedef int (*git_attr_foreach_cb)(const char *name, const char *value, void *payload);
 
 /**
@@ -196,13 +212,8 @@ typedef int (*git_attr_foreach_cb)(const char *name, const char *value, void *pa
  * @param path Path inside the repo to check attributes.  This does not have
  *             to exist, but if it does not, then it will be treated as a
  *             plain file (i.e. not a directory).
- * @param callback Function to invoke on each attribute name and value.  The
- *             value may be NULL is the attribute is explicitly set to
- *             UNSPECIFIED using the '!' sign.  Callback will be invoked
- *             only once per attribute name, even if there are multiple
- *             rules for a given file.  The highest priority rule will be
- *             used.  Return a non-zero value from this to stop looping.
- *             The value will be returned from `git_attr_foreach`.
+ * @param callback Function to invoke on each attribute name and value.
+ *                 See git_attr_foreach_cb.
  * @param payload Passed on as extra parameter to callback function.
  * @return 0 on success, non-zero callback return value, or error code
  */
diff --git a/include/git2/blame.h b/include/git2/blame.h
index 84bb7f94c..34cb69916 100644
--- a/include/git2/blame.h
+++ b/include/git2/blame.h
@@ -48,33 +48,38 @@ typedef enum {
 /**
  * Blame options structure
  *
- * Use zeros to indicate default settings.  It's easiest to use the
- * `GIT_BLAME_OPTIONS_INIT` macro:
- *     git_blame_options opts = GIT_BLAME_OPTIONS_INIT;
+ * Initialize with `GIT_BLAME_OPTIONS_INIT`. Alternatively, you can
+ * use `git_blame_init_options`.
  *
- * - `flags` is a combination of the `git_blame_flag_t` values above.
- * - `min_match_characters` is the lower bound on the number of alphanumeric
- *   characters that must be detected as moving/copying within a file for it to
- *   associate those lines with the parent commit. The default value is 20.
- *   This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
- *   flags are specified.
- * - `newest_commit` is the id of the newest commit to consider.  The default
- *                   is HEAD.
- * - `oldest_commit` is the id of the oldest commit to consider.  The default
- *                   is the first commit encountered with a NULL parent.
- *	- `min_line` is the first line in the file to blame.  The default is 1 (line
- *	             numbers start with 1).
- *	- `max_line` is the last line in the file to blame.  The default is the last
- *	             line of the file.
  */
 typedef struct git_blame_options {
 	unsigned int version;
 
+	/** A combination of `git_blame_flag_t` */
 	uint32_t flags;
+	/** The lower bound on the number of alphanumeric
+	 *   characters that must be detected as moving/copying within a file for it to
+	 *   associate those lines with the parent commit. The default value is 20.
+	 *   This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
+	 *   flags are specified.
+	 */
 	uint16_t min_match_characters;
+	/** The id of the newest commit to consider. The default is HEAD. */
 	git_oid newest_commit;
+	/**
+	 * The id of the oldest commit to consider.
+	 * The default is the first commit encountered with a NULL parent.
+	 */
 	git_oid oldest_commit;
+	/**
+	 * The first line in the file to blame.
+	 * The default is 1 (line numbers start with 1).
+	 */
 	size_t min_line;
+	/**
+	 * The last line in the file to blame.
+	 * The default is the last line of the file.
+	 */
 	size_t max_line;
 } git_blame_options;
 
@@ -82,11 +87,13 @@ typedef struct git_blame_options {
 #define GIT_BLAME_OPTIONS_INIT {GIT_BLAME_OPTIONS_VERSION}
 
 /**
- * Initializes a `git_blame_options` with default values. Equivalent to
- * creating an instance with GIT_BLAME_OPTIONS_INIT.
+ * Initialize git_blame_options structure
  *
- * @param opts The `git_blame_options` struct to initialize
- * @param version Version of struct; pass `GIT_BLAME_OPTIONS_VERSION`
+ * Initializes a `git_blame_options` with default values. Equivalent to creating
+ * an instance with GIT_BLAME_OPTIONS_INIT.
+ *
+ * @param opts The `git_blame_options` struct to initialize.
+ * @param version The struct version; pass `GIT_BLAME_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_blame_init_options(
@@ -128,7 +135,7 @@ typedef struct git_blame_hunk {
 } git_blame_hunk;
 
 
-/* Opaque structure to hold blame results */
+/** Opaque structure to hold blame results */
 typedef struct git_blame git_blame;
 
 /**
diff --git a/include/git2/branch.h b/include/git2/branch.h
index 88fe723a0..8a4ce29a9 100644
--- a/include/git2/branch.h
+++ b/include/git2/branch.h
@@ -278,7 +278,7 @@ GIT_EXTERN(int) git_branch_remote_name(
 
 
 /**
- * Retrieve the name fo the upstream remote of a local branch
+ * Retrieve the name of the upstream remote of a local branch
  *
  * @param buf the buffer into which to write the name
  * @param repo the repository in which to look
diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index c7b0c83ef..7ba0df871 100644
--- a/include/git2/checkout.h
+++ b/include/git2/checkout.h
@@ -243,10 +243,9 @@ typedef void (*git_checkout_perfdata_cb)(
 /**
  * Checkout options structure
  *
- * Zero out for defaults.  Initialize with `GIT_CHECKOUT_OPTIONS_INIT` macro to
- * correctly set the `version` field.  E.g.
+ * Initialize with `GIT_CHECKOUT_OPTIONS_INIT`. Alternatively, you can
+ * use `git_checkout_init_options`.
  *
- *		git_checkout_options opts = GIT_CHECKOUT_OPTIONS_INIT;
  */
 typedef struct git_checkout_options {
 	unsigned int version;
@@ -298,13 +297,15 @@ typedef struct git_checkout_options {
 #define GIT_CHECKOUT_OPTIONS_INIT {GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE}
 
 /**
-* Initializes a `git_checkout_options` with default values. Equivalent to
-* creating an instance with GIT_CHECKOUT_OPTIONS_INIT.
-*
-* @param opts the `git_checkout_options` struct to initialize.
-* @param version Version of struct; pass `GIT_CHECKOUT_OPTIONS_VERSION`
-* @return Zero on success; -1 on failure.
-*/
+ * Initialize git_checkout_options structure
+ *
+ * Initializes a `git_checkout_options` with default values. Equivalent to creating
+ * an instance with GIT_CHECKOUT_OPTIONS_INIT.
+ *
+ * @param opts The `git_checkout_options` struct to initialize.
+ * @param version The struct version; pass `GIT_CHECKOUT_OPTIONS_VERSION`.
+ * @return Zero on success; -1 on failure.
+ */
 GIT_EXTERN(int) git_checkout_init_options(
 	git_checkout_options *opts,
 	unsigned int version);
diff --git a/include/git2/cherrypick.h b/include/git2/cherrypick.h
index edec96a94..ca6f72075 100644
--- a/include/git2/cherrypick.h
+++ b/include/git2/cherrypick.h
@@ -37,11 +37,13 @@ typedef struct {
 #define GIT_CHERRYPICK_OPTIONS_INIT {GIT_CHERRYPICK_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT}
 
 /**
- * Initializes a `git_cherrypick_options` with default values. Equivalent to
- * creating an instance with GIT_CHERRYPICK_OPTIONS_INIT.
+ * Initialize git_cherrypick_options structure
  *
- * @param opts the `git_cherrypick_options` struct to initialize
- * @param version Version of struct; pass `GIT_CHERRYPICK_OPTIONS_VERSION`
+ * Initializes a `git_cherrypick_options` with default values. Equivalent to creating
+ * an instance with GIT_CHERRYPICK_OPTIONS_INIT.
+ *
+ * @param opts The `git_cherrypick_options` struct to initialize.
+ * @param version The struct version; pass `GIT_CHERRYPICK_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_cherrypick_init_options(
diff --git a/include/git2/clone.h b/include/git2/clone.h
index 9e23aaccb..469031700 100644
--- a/include/git2/clone.h
+++ b/include/git2/clone.h
@@ -96,9 +96,9 @@ typedef int (*git_repository_create_cb)(
 /**
  * Clone options structure
  *
- * Use the GIT_CLONE_OPTIONS_INIT to get the default settings, like this:
+ * Initialize with `GIT_CLONE_OPTIONS_INIT`. Alternatively, you can
+ * use `git_clone_init_options`.
  *
- *		git_clone_options opts = GIT_CLONE_OPTIONS_INIT;
  */
 typedef struct git_clone_options {
 	unsigned int version;
@@ -169,11 +169,13 @@ typedef struct git_clone_options {
 	GIT_FETCH_OPTIONS_INIT }
 
 /**
- * Initializes a `git_clone_options` with default values. Equivalent to
- * creating an instance with GIT_CLONE_OPTIONS_INIT.
+ * Initialize git_clone_options structure
  *
- * @param opts The `git_clone_options` struct to initialize
- * @param version Version of struct; pass `GIT_CLONE_OPTIONS_VERSION`
+ * Initializes a `git_clone_options` with default values. Equivalent to creating
+ * an instance with GIT_CLONE_OPTIONS_INIT.
+ *
+ * @param opts The `git_clone_options` struct to initialize.
+ * @param version The struct version; pass `GIT_CLONE_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_clone_init_options(
diff --git a/include/git2/describe.h b/include/git2/describe.h
index eb0355bb3..56f119b2d 100644
--- a/include/git2/describe.h
+++ b/include/git2/describe.h
@@ -36,10 +36,9 @@ typedef enum {
 /**
  * Describe options structure
  *
- * Initialize with `GIT_DESCRIBE_OPTIONS_INIT` macro to correctly set
- * the `version` field.  E.g.
+ * Initialize with `GIT_DESCRIBE_OPTIONS_INIT`. Alternatively, you can
+ * use `git_describe_init_options`.
  *
- *		git_describe_options opts = GIT_DESCRIBE_OPTIONS_INIT;
  */
 typedef struct git_describe_options {
 	unsigned int version;
@@ -70,10 +69,24 @@ typedef struct git_describe_options {
 	GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \
 }
 
+/**
+ * Initialize git_describe_options structure
+ *
+ * Initializes a `git_describe_options` with default values. Equivalent to creating
+ * an instance with GIT_DESCRIBE_OPTIONS_INIT.
+ *
+ * @param opts The `git_describe_options` struct to initialize.
+ * @param version The struct version; pass `GIT_DESCRIBE_OPTIONS_VERSION`.
+ * @return Zero on success; -1 on failure.
+ */
 GIT_EXTERN(int) git_describe_init_options(git_describe_options *opts, unsigned int version);
 
 /**
- * Options for formatting the describe string
+ * Describe format options structure
+ *
+ * Initialize with `GIT_DESCRIBE_FORMAT_OPTIONS_INIT`. Alternatively, you can
+ * use `git_describe_format_init_options`.
+ *
  */
 typedef struct {
 	unsigned int version;
@@ -103,6 +116,16 @@ typedef struct {
 		GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \
  }
 
+/**
+ * Initialize git_describe_format_options structure
+ *
+ * Initializes a `git_describe_format_options` with default values. Equivalent to creating
+ * an instance with GIT_DESCRIBE_FORMAT_OPTIONS_INIT.
+ *
+ * @param opts The `git_describe_format_options` struct to initialize.
+ * @param version The struct version; pass `GIT_DESCRIBE_FORMAT_OPTIONS_VERSION`.
+ * @return Zero on success; -1 on failure.
+ */
 GIT_EXTERN(int) git_describe_init_format_options(git_describe_format_options *opts, unsigned int version);
 
 /**
diff --git a/include/git2/diff.h b/include/git2/diff.h
index 86009f583..b7240ff98 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -437,11 +437,13 @@ typedef struct {
 	{GIT_DIFF_OPTIONS_VERSION, 0, GIT_SUBMODULE_IGNORE_UNSPECIFIED, {NULL,0}, NULL, NULL, NULL, 3}
 
 /**
- * Initializes a `git_diff_options` with default values. Equivalent to
- * creating an instance with GIT_DIFF_OPTIONS_INIT.
+ * Initialize git_diff_options structure
  *
- * @param opts The `git_diff_options` struct to initialize
- * @param version Version of struct; pass `GIT_DIFF_OPTIONS_VERSION`
+ * Initializes a `git_diff_options` with default values. Equivalent to creating
+ * an instance with GIT_DIFF_OPTIONS_INIT.
+ *
+ * @param opts The `git_diff_options` struct to initialize.
+ * @param version The struct version; pass `GIT_DIFF_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_diff_init_options(
@@ -732,11 +734,13 @@ typedef struct {
 #define GIT_DIFF_FIND_OPTIONS_INIT {GIT_DIFF_FIND_OPTIONS_VERSION}
 
 /**
- * Initializes a `git_diff_find_options` with default values. Equivalent to
- * creating an instance with GIT_DIFF_FIND_OPTIONS_INIT.
+ * Initialize git_diff_find_options structure
+ *
+ * Initializes a `git_diff_find_options` with default values. Equivalent to creating
+ * an instance with GIT_DIFF_FIND_OPTIONS_INIT.
  *
- * @param opts The `git_diff_find_options` struct to initialize
- * @param version Version of struct; pass `GIT_DIFF_FIND_OPTIONS_VERSION`
+ * @param opts The `git_diff_find_options` struct to initialize.
+ * @param version The struct version; pass `GIT_DIFF_FIND_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_diff_find_init_options(
@@ -1394,12 +1398,13 @@ GIT_EXTERN(int) git_diff_commit_as_email(
 	const git_diff_options *diff_opts);
 
 /**
- * Initializes a `git_diff_format_email_options` with default values.
+ * Initialize git_diff_format_email_options structure
  *
- * Equivalent to creating an instance with GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT.
+ * Initializes a `git_diff_format_email_options` with default values. Equivalent
+ * to creating an instance with GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT.
  *
- * @param opts The `git_diff_format_email_options` struct to initialize
- * @param version Version of struct; pass `GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION`
+ * @param opts The `git_blame_options` struct to initialize.
+ * @param version The struct version; pass `GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_diff_format_email_init_options(
@@ -1409,8 +1414,9 @@ GIT_EXTERN(int) git_diff_format_email_init_options(
 /**
  * Patch ID options structure
  *
- * Initialize with `GIT_DIFF_PATCHID_OPTIONS_INIT` macro to
- * correctly set the default values and version.
+ * Initialize with `GIT_PATCHID_OPTIONS_INIT`. Alternatively, you can
+ * use `git_patchid_init_options`.
+ *
  */
 typedef struct git_diff_patchid_options {
 	unsigned int version;
@@ -1420,10 +1426,14 @@ typedef struct git_diff_patchid_options {
 #define GIT_DIFF_PATCHID_OPTIONS_INIT { GIT_DIFF_PATCHID_OPTIONS_VERSION }
 
 /**
- * Initialize `git_diff_patchid_options` structure.
+ * Initialize git_diff_patchid_options structure
  *
- * Initializes the structure with default values. Equivalent to
+ * Initializes a `git_diff_patchid_options` with default values. Equivalent to
  * creating an instance with `GIT_DIFF_PATCHID_OPTIONS_INIT`.
+ *
+ * @param opts The `git_diff_patchid_options` struct to initialize.
+ * @param version The struct version; pass `GIT_DIFF_PATCHID_OPTIONS_VERSION`.
+ * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_diff_patchid_init_options(
 	git_diff_patchid_options *opts,
diff --git a/include/git2/merge.h b/include/git2/merge.h
index 80ef864d1..47bf32daa 100644
--- a/include/git2/merge.h
+++ b/include/git2/merge.h
@@ -203,12 +203,13 @@ typedef struct {
 #define GIT_MERGE_FILE_OPTIONS_INIT {GIT_MERGE_FILE_OPTIONS_VERSION}
 
 /**
+ * Initialize git_merge_file_options structure
+ *
  * Initializes a `git_merge_file_options` with default values. Equivalent to
- * creating an instance with GIT_MERGE_FILE_OPTIONS_INIT.
+ * creating an instance with `GIT_MERGE_FILE_OPTIONS_INIT`.
  *
- * @param opts the `git_merge_file_options` instance to initialize.
- * @param version the version of the struct; you should pass
- *        `GIT_MERGE_FILE_OPTIONS_VERSION` here.
+ * @param opts The `git_merge_file_options` struct to initialize.
+ * @param version The struct version; pass `GIT_MERGE_FILE_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_merge_file_init_options(
@@ -300,12 +301,13 @@ typedef struct {
 	GIT_MERGE_OPTIONS_VERSION, GIT_MERGE_FIND_RENAMES }
 
 /**
+ * Initialize git_merge_options structure
+ *
  * Initializes a `git_merge_options` with default values. Equivalent to
- * creating an instance with GIT_MERGE_OPTIONS_INIT.
+ * creating an instance with `GIT_MERGE_OPTIONS_INIT`.
  *
- * @param opts the `git_merge_options` instance to initialize.
- * @param version the version of the struct; you should pass
- *        `GIT_MERGE_OPTIONS_VERSION` here.
+ * @param opts The `git_merge_options` struct to initialize.
+ * @param version The struct version; pass `GIT_MERGE_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_merge_init_options(
diff --git a/include/git2/proxy.h b/include/git2/proxy.h
index 06d46d340..5f9d27f30 100644
--- a/include/git2/proxy.h
+++ b/include/git2/proxy.h
@@ -80,10 +80,14 @@ typedef struct {
 #define GIT_PROXY_OPTIONS_INIT {GIT_PROXY_OPTIONS_VERSION}
 
 /**
- * Initialize a proxy options structure
+ * Initialize git_proxy_options structure
  *
- * @param opts the options struct to initialize
- * @param version the version of the struct, use `GIT_PROXY_OPTIONS_VERSION`
+ * Initializes a `git_proxy_options` with default values. Equivalent to
+ * creating an instance with `GIT_PROXY_OPTIONS_INIT`.
+ *
+ * @param opts The `git_proxy_options` struct to initialize.
+ * @param version The struct version; pass `GIT_PROXY_OPTIONS_VERSION`.
+ * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_proxy_init_options(git_proxy_options *opts, unsigned int version);
 
diff --git a/include/git2/rebase.h b/include/git2/rebase.h
index 9b9065ee4..f6b2e20ad 100644
--- a/include/git2/rebase.h
+++ b/include/git2/rebase.h
@@ -11,6 +11,8 @@
 #include "types.h"
 #include "oid.h"
 #include "annotated_commit.h"
+#include "merge.h"
+#include "checkout.h"
 
 /**
  * @file git2/rebase.h
@@ -145,12 +147,13 @@ typedef struct {
 } git_rebase_operation;
 
 /**
+ * Initialize git_rebase_options structure
+ *
  * Initializes a `git_rebase_options` with default values. Equivalent to
- * creating an instance with GIT_REBASE_OPTIONS_INIT.
+ * creating an instance with `GIT_REBASE_OPTIONS_INIT`.
  *
- * @param opts the `git_rebase_options` instance to initialize.
- * @param version the version of the struct; you should pass
- *        `GIT_REBASE_OPTIONS_VERSION` here.
+ * @param opts The `git_rebase_options` struct to initialize.
+ * @param version The struct version; pass `GIT_REBASE_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_rebase_init_options(
diff --git a/include/git2/remote.h b/include/git2/remote.h
index 3d463dec1..757515d8a 100644
--- a/include/git2/remote.h
+++ b/include/git2/remote.h
@@ -596,12 +596,13 @@ typedef struct {
 				 GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED, GIT_PROXY_OPTIONS_INIT }
 
 /**
+ * Initialize git_fetch_options structure
+ *
  * Initializes a `git_fetch_options` with default values. Equivalent to
- * creating an instance with GIT_FETCH_OPTIONS_INIT.
+ * creating an instance with `GIT_FETCH_OPTIONS_INIT`.
  *
- * @param opts the `git_fetch_options` instance to initialize.
- * @param version the version of the struct; you should pass
- *        `GIT_FETCH_OPTIONS_VERSION` here.
+ * @param opts The `git_fetch_options` struct to initialize.
+ * @param version The struct version; pass `GIT_FETCH_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_fetch_init_options(
@@ -645,12 +646,13 @@ typedef struct {
 #define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 0, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT }
 
 /**
+ * Initialize git_push_options structure
+ *
  * Initializes a `git_push_options` with default values. Equivalent to
- * creating an instance with GIT_PUSH_OPTIONS_INIT.
+ * creating an instance with `GIT_PUSH_OPTIONS_INIT`.
  *
- * @param opts the `git_push_options` instance to initialize.
- * @param version the version of the struct; you should pass
- *        `GIT_PUSH_OPTIONS_VERSION` here.
+ * @param opts The `git_push_options` struct to initialize.
+ * @param version The struct version; pass `GIT_PUSH_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_push_init_options(
diff --git a/include/git2/repository.h b/include/git2/repository.h
index 6e0c1f71e..a39ebb99b 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -301,11 +301,13 @@ typedef struct {
 #define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION}
 
 /**
- * Initializes a `git_repository_init_options` with default values. Equivalent
- * to creating an instance with GIT_REPOSITORY_INIT_OPTIONS_INIT.
+ * Initialize git_repository_init_options structure
  *
- * @param opts the `git_repository_init_options` struct to initialize
- * @param version Version of struct; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`
+ * Initializes a `git_repository_init_options` with default values. Equivalent to
+ * creating an instance with `GIT_REPOSITORY_INIT_OPTIONS_INIT`.
+ *
+ * @param opts The `git_repository_init_options` struct to initialize.
+ * @param version The struct version; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_repository_init_init_options(
@@ -368,7 +370,7 @@ GIT_EXTERN(int) git_repository_head_for_worktree(git_reference **out, git_reposi
  */
 GIT_EXTERN(int) git_repository_head_detached(git_repository *repo);
 
-/*
+/**
  * Check if a worktree's HEAD is detached
  *
  * A worktree's HEAD is detached when it points directly to a
diff --git a/include/git2/revert.h b/include/git2/revert.h
index 82dbadcfc..260ad044b 100644
--- a/include/git2/revert.h
+++ b/include/git2/revert.h
@@ -37,11 +37,13 @@ typedef struct {
 #define GIT_REVERT_OPTIONS_INIT {GIT_REVERT_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT}
 
 /**
+ * Initialize git_revert_options structure
+ *
  * Initializes a `git_revert_options` with default values. Equivalent to
- * creating an instance with GIT_REVERT_OPTIONS_INIT.
+ * creating an instance with `GIT_REVERT_OPTIONS_INIT`.
  *
- * @param opts the `git_revert_options` struct to initialize
- * @param version Version of struct; pass `GIT_REVERT_OPTIONS_VERSION`
+ * @param opts The `git_revert_options` struct to initialize.
+ * @param version The struct version; pass `GIT_REVERT_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_revert_init_options(
diff --git a/include/git2/stash.h b/include/git2/stash.h
index 3af9cde38..1fdbeb64a 100644
--- a/include/git2/stash.h
+++ b/include/git2/stash.h
@@ -9,6 +9,7 @@
 
 #include "common.h"
 #include "types.h"
+#include "checkout.h"
 
 /**
  * @file git2/stash.h
@@ -80,6 +81,7 @@ typedef enum {
 	GIT_STASH_APPLY_REINSTATE_INDEX = (1 << 0),
 } git_stash_apply_flags;
 
+/** Stash apply progression states */
 typedef enum {
 	GIT_STASH_APPLY_PROGRESS_NONE = 0,
 
@@ -114,12 +116,12 @@ typedef int (*git_stash_apply_progress_cb)(
 	git_stash_apply_progress_t progress,
 	void *payload);
 
-/** Stash application options structure.
+/**
+ * Stash application options structure
  *
- * Initialize with the `GIT_STASH_APPLY_OPTIONS_INIT` macro to set
- * sensible defaults; for example:
+ * Initialize with `GIT_STASH_APPLY_OPTIONS_INIT`. Alternatively, you can
+ * use `git_stash_apply_init_options`.
  *
- *		git_stash_apply_options opts = GIT_STASH_APPLY_OPTIONS_INIT;
  */
 typedef struct git_stash_apply_options {
 	unsigned int version;
@@ -142,12 +144,13 @@ typedef struct git_stash_apply_options {
 	GIT_CHECKOUT_OPTIONS_INIT }
 
 /**
+ * Initialize git_stash_apply_options structure
+ *
  * Initializes a `git_stash_apply_options` with default values. Equivalent to
- * creating an instance with GIT_STASH_APPLY_OPTIONS_INIT.
+ * creating an instance with `GIT_STASH_APPLY_OPTIONS_INIT`.
  *
- * @param opts the `git_stash_apply_options` instance to initialize.
- * @param version the version of the struct; you should pass
- *        `GIT_STASH_APPLY_OPTIONS_INIT` here.
+ * @param opts The `git_stash_apply_options` struct to initialize.
+ * @param version The struct version; pass `GIT_STASH_APPLY_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_stash_apply_init_options(
diff --git a/include/git2/status.h b/include/git2/status.h
index 4b86818b7..bba0d0537 100644
--- a/include/git2/status.h
+++ b/include/git2/status.h
@@ -9,6 +9,8 @@
 
 #include "common.h"
 #include "types.h"
+#include "strarray.h"
+#include "diff.h"
 
 /**
  * @file git2/status.h
@@ -189,11 +191,13 @@ typedef struct {
 #define GIT_STATUS_OPTIONS_INIT {GIT_STATUS_OPTIONS_VERSION}
 
 /**
+ * Initialize git_status_options structure
+ *
  * Initializes a `git_status_options` with default values. Equivalent to
- * creating an instance with GIT_STATUS_OPTIONS_INIT.
+ * creating an instance with `GIT_STATUS_OPTIONS_INIT`.
  *
- * @param opts The `git_status_options` instance to initialize.
- * @param version Version of struct; pass `GIT_STATUS_OPTIONS_VERSION`
+ * @param opts The `git_status_options` struct to initialize.
+ * @param version The struct version; pass `GIT_STATUS_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_status_init_options(
diff --git a/include/git2/submodule.h b/include/git2/submodule.h
index b2b3039fe..c5cf00661 100644
--- a/include/git2/submodule.h
+++ b/include/git2/submodule.h
@@ -121,10 +121,9 @@ typedef int (*git_submodule_cb)(
 /**
  * Submodule update options structure
  *
- * Use the GIT_SUBMODULE_UPDATE_OPTIONS_INIT to get the default settings,
- * like this:
+ * Initialize with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. Alternatively, you can
+ * use `git_submodule_update_init_options`.
  *
- * git_submodule_update_options opts = GIT_SUBMODULE_UPDATE_OPTIONS_INIT;
  */
 typedef struct git_submodule_update_options {
 	unsigned int version;
@@ -160,11 +159,13 @@ typedef struct git_submodule_update_options {
 	GIT_FETCH_OPTIONS_INIT, 1 }
 
 /**
- * Initializes a `git_submodule_update_options` with default values.
- * Equivalent to creating an instance with GIT_SUBMODULE_UPDATE_OPTIONS_INIT.
+ * Initialize git_submodule_update_options structure
  *
- * @param opts The `git_submodule_update_options` instance to initialize.
- * @param version Version of struct; pass `GIT_SUBMODULE_UPDATE_OPTIONS_VERSION`
+ * Initializes a `git_submodule_update_options` with default values. Equivalent to
+ * creating an instance with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`.
+ *
+ * @param opts The `git_submodule_update_options` struct to initialize.
+ * @param version The struct version; pass `GIT_SUBMODULE_UPDATE_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_submodule_update_init_options(
diff --git a/include/git2/sys/index.h b/include/git2/sys/index.h
index 2e2b87e68..f1900df42 100644
--- a/include/git2/sys/index.h
+++ b/include/git2/sys/index.h
@@ -7,6 +7,9 @@
 #ifndef INCLUDE_sys_git_index_h__
 #define INCLUDE_sys_git_index_h__
 
+#include "git2/common.h"
+#include "git2/types.h"
+
 /**
  * @file git2/sys/index.h
  * @brief Low-level Git index manipulation routines
diff --git a/include/git2/sys/mempack.h b/include/git2/sys/mempack.h
index 490636b44..63fb38dc8 100644
--- a/include/git2/sys/mempack.h
+++ b/include/git2/sys/mempack.h
@@ -23,61 +23,61 @@
 GIT_BEGIN_DECL
 
 /**
- *	Instantiate a new mempack backend.
+ * Instantiate a new mempack backend.
  *
- *	The backend must be added to an existing ODB with the highest
- *	priority.
+ * The backend must be added to an existing ODB with the highest
+ * priority.
  *
- *		git_mempack_new(&mempacker);
- *		git_repository_odb(&odb, repository);
- *		git_odb_add_backend(odb, mempacker, 999);
+ *     git_mempack_new(&mempacker);
+ *     git_repository_odb(&odb, repository);
+ *     git_odb_add_backend(odb, mempacker, 999);
  *
- *	Once the backend has been loaded, all writes to the ODB will
- *	instead be queued in memory, and can be finalized with
- *	`git_mempack_dump`.
+ * Once the backend has been loaded, all writes to the ODB will
+ * instead be queued in memory, and can be finalized with
+ * `git_mempack_dump`.
  *
- *	Subsequent reads will also be served from the in-memory store
- *	to ensure consistency, until the memory store is dumped.
+ * Subsequent reads will also be served from the in-memory store
+ * to ensure consistency, until the memory store is dumped.
  *
- *	@param out Pointer where to store the ODB backend
- *	@return 0 on success; error code otherwise
+ * @param out Pointer where to store the ODB backend
+ * @return 0 on success; error code otherwise
  */
 GIT_EXTERN(int) git_mempack_new(git_odb_backend **out);
 
 /**
- *	Dump all the queued in-memory writes to a packfile.
+ * Dump all the queued in-memory writes to a packfile.
  *
- *	The contents of the packfile will be stored in the given buffer.
- *	It is the caller's responsibility to ensure that the generated
- *	packfile is available to the repository (e.g. by writing it
- *	to disk, or doing something crazy like distributing it across
- *	several copies of the repository over a network).
+ * The contents of the packfile will be stored in the given buffer.
+ * It is the caller's responsibility to ensure that the generated
+ * packfile is available to the repository (e.g. by writing it
+ * to disk, or doing something crazy like distributing it across
+ * several copies of the repository over a network).
  *
- *	Once the generated packfile is available to the repository,
- *	call `git_mempack_reset` to cleanup the memory store.
+ * Once the generated packfile is available to the repository,
+ * call `git_mempack_reset` to cleanup the memory store.
  *
- *	Calling `git_mempack_reset` before the packfile has been
- *	written to disk will result in an inconsistent repository
- *	(the objects in the memory store won't be accessible).
+ * Calling `git_mempack_reset` before the packfile has been
+ * written to disk will result in an inconsistent repository
+ * (the objects in the memory store won't be accessible).
  *
- *	@param pack Buffer where to store the raw packfile
- *	@param repo The active repository where the backend is loaded
- *	@param backend The mempack backend
- *	@return 0 on success; error code otherwise
+ * @param pack Buffer where to store the raw packfile
+ * @param repo The active repository where the backend is loaded
+ * @param backend The mempack backend
+ * @return 0 on success; error code otherwise
  */
 GIT_EXTERN(int) git_mempack_dump(git_buf *pack, git_repository *repo, git_odb_backend *backend);
 
 /**
- *	Reset the memory packer by clearing all the queued objects.
+ * Reset the memory packer by clearing all the queued objects.
  *
- *	This assumes that `git_mempack_dump` has been called before to
- *	store all the queued objects into a single packfile.
+ * This assumes that `git_mempack_dump` has been called before to
+ * store all the queued objects into a single packfile.
  *
- *	Alternatively, call `reset` without a previous dump to "undo"
- *	all the recently written objects, giving transaction-like
- *	semantics to the Git repository.
+ * Alternatively, call `reset` without a previous dump to "undo"
+ * all the recently written objects, giving transaction-like
+ * semantics to the Git repository.
  *
- *	@param backend The mempack backend
+ * @param backend The mempack backend
  */
 GIT_EXTERN(void) git_mempack_reset(git_odb_backend *backend);
 
diff --git a/include/git2/sys/merge.h b/include/git2/sys/merge.h
index eed106c07..f07997d2e 100644
--- a/include/git2/sys/merge.h
+++ b/include/git2/sys/merge.h
@@ -7,10 +7,15 @@
 #ifndef INCLUDE_sys_git_merge_h__
 #define INCLUDE_sys_git_merge_h__
 
+#include "git2/common.h"
+#include "git2/types.h"
+#include "git2/index.h"
+#include "git2/merge.h"
+
 /**
  * @file git2/sys/merge.h
  * @brief Git merge driver backend and plugin routines
- * @defgroup git_backend Git custom backend APIs
+ * @defgroup git_merge Git merge driver APIs
  * @ingroup Git
  * @{
  */
diff --git a/include/git2/transaction.h b/include/git2/transaction.h
index 00ca13993..4938570b5 100644
--- a/include/git2/transaction.h
+++ b/include/git2/transaction.h
@@ -8,6 +8,7 @@
 #define INCLUDE_git_transaction_h__
 
 #include "common.h"
+#include "types.h"
 
 /**
  * @file git2/transaction.h
diff --git a/include/git2/types.h b/include/git2/types.h
index ad34e0170..67e5bd155 100644
--- a/include/git2/types.h
+++ b/include/git2/types.h
@@ -63,6 +63,9 @@ typedef int64_t git_time_t;
 
 #endif
 
+#include "buffer.h"
+#include "oid.h"
+
 /** Basic type (loose or packed) of any Git object. */
 typedef enum {
 	GIT_OBJ_ANY = -2,		/**< Object can be any of the following */
@@ -212,7 +215,7 @@ typedef enum {
 	GIT_FILEMODE_COMMIT              = 0160000,
 } git_filemode_t;
 
-/*
+/**
  * A refspec specifies the mapping between remote and local reference
  * names when fetch or pushing.
  */
@@ -422,9 +425,9 @@ typedef enum {
 	GIT_SUBMODULE_RECURSE_ONDEMAND = 2,
 } git_submodule_recurse_t;
 
-/** A type to write in a streaming fashion, for example, for filters. */
 typedef struct git_writestream git_writestream;
 
+/** A type to write in a streaming fashion, for example, for filters. */
 struct git_writestream {
 	int (*write)(git_writestream *stream, const char *buffer, size_t len);
 	int (*close)(git_writestream *stream);
diff --git a/include/git2/worktree.h b/include/git2/worktree.h
index d6d4ce5cf..d1b4f84c2 100644
--- a/include/git2/worktree.h
+++ b/include/git2/worktree.h
@@ -74,6 +74,13 @@ GIT_EXTERN(void) git_worktree_free(git_worktree *wt);
  */
 GIT_EXTERN(int) git_worktree_validate(const git_worktree *wt);
 
+/**
+ * Worktree add options structure
+ *
+ * Initialize with `GIT_WORKTREE_ADD_OPTIONS_INIT`. Alternatively, you can
+ * use `git_worktree_add_init_options`.
+ *
+ */
 typedef struct git_worktree_add_options {
 	unsigned int version;
 
@@ -85,12 +92,13 @@ typedef struct git_worktree_add_options {
 #define GIT_WORKTREE_ADD_OPTIONS_INIT {GIT_WORKTREE_ADD_OPTIONS_VERSION,0,NULL}
 
 /**
- * Initializes a `git_worktree_add_options` with default vaules.
- * Equivalent to creating an instance with
- * GIT_WORKTREE_ADD_OPTIONS_INIT.
+ * Initialize git_worktree_add_options structure
+ *
+ * Initializes a `git_worktree_add_options` with default values. Equivalent to
+ * creating an instance with `GIT_WORKTREE_ADD_OPTIONS_INIT`.
  *
- * @param opts the struct to initialize
- * @param version Verison of struct; pass `GIT_WORKTREE_ADD_OPTIONS_VERSION`
+ * @param opts The `git_worktree_add_options` struct to initialize.
+ * @param version The struct version; pass `GIT_WORKTREE_ADD_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 int git_worktree_add_init_options(git_worktree_add_options *opts,
@@ -180,6 +188,13 @@ typedef enum {
 	GIT_WORKTREE_PRUNE_WORKING_TREE = 1u << 2,
 } git_worktree_prune_t;
 
+/**
+ * Worktree prune options structure
+ *
+ * Initialize with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`. Alternatively, you can
+ * use `git_worktree_prune_init_options`.
+ *
+ */
 typedef struct git_worktree_prune_options {
 	unsigned int version;
 
@@ -190,12 +205,13 @@ typedef struct git_worktree_prune_options {
 #define GIT_WORKTREE_PRUNE_OPTIONS_INIT {GIT_WORKTREE_PRUNE_OPTIONS_VERSION,0}
 
 /**
- * Initializes a `git_worktree_prune_options` with default vaules.
- * Equivalent to creating an instance with
- * GIT_WORKTREE_PRUNE_OPTIONS_INIT.
+ * Initialize git_worktree_prune_options structure
+ *
+ * Initializes a `git_worktree_prune_options` with default values. Equivalent to
+ * creating an instance with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`.
  *
- * @param opts the struct to initialize
- * @param version Verison of struct; pass `GIT_WORKTREE_PRUNE_OPTIONS_VERSION`
+ * @param opts The `git_worktree_prune_options` struct to initialize.
+ * @param version The struct version; pass `GIT_WORKTREE_PRUNE_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_worktree_prune_init_options(