Skip to content

G
git2
Commit ca5a15e5 by Etienne Samson
Options

docs: standardize comment block for git_*_init_options functions

parent 8ee183a2
Showing with 157 additions and 84 deletions
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(
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment