docs: standardize struct git_*_options comments

8 files changed, 26 insertions, 27 deletions

diff --git a/include/git2/blame.h b/include/git2/blame.h
index 64e745808..34cb69916 100644
--- a/include/git2/blame.h
+++ b/include/git2/blame.h
@@ -48,9 +48,8 @@ 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`.
  *
  */
 typedef struct git_blame_options {
diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index 9a1cdfbdd..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;
diff --git a/include/git2/clone.h b/include/git2/clone.h
index 29a229bb8..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;
diff --git a/include/git2/describe.h b/include/git2/describe.h
index 30a689ab8..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;
@@ -83,7 +82,11 @@ typedef struct git_describe_options {
 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;
diff --git a/include/git2/diff.h b/include/git2/diff.h
index 5a2e29960..b7240ff98 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -1414,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;
diff --git a/include/git2/stash.h b/include/git2/stash.h
index 514823498..1fdbeb64a 100644
--- a/include/git2/stash.h
+++ b/include/git2/stash.h
@@ -116,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;
diff --git a/include/git2/submodule.h b/include/git2/submodule.h
index 762f6319d..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;
diff --git a/include/git2/worktree.h b/include/git2/worktree.h
index fa4b57802..d1b4f84c2 100644
--- a/include/git2/worktree.h
+++ b/include/git2/worktree.h
@@ -77,10 +77,9 @@ 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.
+ * Initialize with `GIT_WORKTREE_ADD_OPTIONS_INIT`. Alternatively, you can
+ * use `git_worktree_add_init_options`.
  *
- *		git_worktree_add_options opts = GIT_WORKTREE_ADD_OPTIONS_INIT;
  */
 typedef struct git_worktree_add_options {
 	unsigned int version;
@@ -192,10 +191,9 @@ typedef enum {
 /**
  * Worktree prune options structure
  *
- * Zero out for defaults.  Initialize with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`
- * macro to correctly set the `version` field.  E.g.
+ * Initialize with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`. Alternatively, you can
+ * use `git_worktree_prune_init_options`.
  *
- *		git_worktree_prune_options opts = GIT_WORKTREE_PRUNE_OPTIONS_INIT;
  */
 typedef struct git_worktree_prune_options {
 	unsigned int version;