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

Fix docurium missing includes

Author: pks-t

api.docurium

@@ -1,7 +1,7 @@
 {
  "name":   "libgit2",
  "github": "libgit2/libgit2",
- "input":  "include/git2",
+ "input":  "include",
  "prefix": "git_",
  "output": "docs",
  "branch": "gh-pages",

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

include/git2/blame.h

@@ -48,45 +48,52 @@ 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;
 
 #define GIT_BLAME_OPTIONS_VERSION 1
 #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;
 
 /**

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

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

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(

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(

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

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,

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(