docs: standardize comment block for git_*_init_options functions

include/git2/blame.h

@@ -82,11 +82,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(

include/git2/checkout.h

@@ -298,13 +298,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

@@ -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

@@ -70,6 +70,16 @@ 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);
 
 /**
@@ -103,6 +113,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(
@@ -1420,10 +1425,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(

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

include/git2/rebase.h

@@ -147,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(

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(

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(

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(

include/git2/stash.h

@@ -144,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(

include/git2/status.h

@@ -191,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(

include/git2/submodule.h

@@ -160,11 +160,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(

include/git2/worktree.h

@@ -74,6 +74,14 @@ GIT_EXTERN(void) git_worktree_free(git_worktree *wt);
  */
 GIT_EXTERN(int) git_worktree_validate(const git_worktree *wt);
 
+/**
+ * Worktree add options structure
+ *
+ * Zero out for defaults.  Initialize with `GIT_WORKTREE_ADD_OPTIONS_INIT`
+ * macro to correctly set the `version` field.  E.g.
+ *
+ *		git_worktree_add_options opts = GIT_WORKTREE_ADD_OPTIONS_INIT;
+ */
 typedef struct git_worktree_add_options {
 	unsigned int version;
 
@@ -85,12 +93,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 +189,14 @@ typedef enum {
 	GIT_WORKTREE_PRUNE_WORKING_TREE = 1u << 2,
 } git_worktree_prune_t;
 
+/**
+ * Worktree prune options structure
+ *
+ * Zero out for defaults.  Initialize with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`
+ * macro to correctly set the `version` field.  E.g.
+ *
+ *		git_worktree_prune_options opts = GIT_WORKTREE_PRUNE_OPTIONS_INIT;
+ */
 typedef struct git_worktree_prune_options {
 	unsigned int version;
 
@@ -190,12 +207,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(