Idea-Studios/libgit2
2
0
Fork 0
mirror of https://github.com/libgit2/libgit2.git synced 2026-06-22 06:26:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: specify out params

Browse Source
This commit is contained in:
Edward Thomson
2026-06-13 17:01:04 +01:00
parent 44c05e5d12
commit da0d84625d
47 changed files with 396 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
include/git2/apply.h
View File

@@ -130,7 +130,7 @@ GIT_EXTERN(int) git_apply_options_init(git_apply_options *opts, unsigned int ver
* Apply a `git_diff` to a `git_tree`, and return the resulting image
* as an index.
*
* @param out the postimage of the application
* @param[out] out the postimage of the application
* @param repo the repository to apply
* @param preimage the tree to apply the diff to
* @param diff the diff to apply

6
include/git2/blame.h
View File

@@ -322,7 +322,7 @@ GIT_EXTERN(const git_blame_hunk *) git_blame_get_hunk_byline(
/**
* Get the blame for a single file in the repository.
*
* @param out pointer that will receive the blame object
* @param[out] out pointer that will receive the blame object
* @param repo repository whose history is to be walked
* @param path path to file to consider
* @param options options for the blame operation or NULL
@@ -339,7 +339,7 @@ GIT_EXTERN(int) git_blame_file(
* buffer contents as the uncommitted changes of the file (the working
* directory contents).
*
* @param out pointer that will receive the blame object
* @param[out] out pointer that will receive the blame object
* @param repo repository whose history is to be walked
* @param path path to file to consider
* @param contents the uncommitted changes
@@ -364,7 +364,7 @@ GIT_EXTERN(int) git_blame_file_from_buffer(
* Lines that differ between the buffer and the committed version are
* marked as having a zero OID for their final_commit_id.
*
* @param out pointer that will receive the resulting blame data
* @param[out] out pointer that will receive the resulting blame data
* @param base cached blame from the history of the file (usually the output
* from git_blame_file)
* @param buffer the (possibly) modified contents of the file

32
include/git2/branch.h
View File

@@ -38,7 +38,7 @@ GIT_BEGIN_DECL
* The branch name will be checked for validity.
* See `git_tag_create()` for rules about valid names.
*
* @param out Pointer where to store the underlying reference.
* @param[out] out Pointer where to store the underlying reference.
* @param repo the repository to create the branch in.
* @param branch_name Name for the branch; this name is
* validated for consistency. It should also not conflict with
@@ -99,7 +99,7 @@ typedef struct git_branch_iterator git_branch_iterator;
/**
* Create an iterator which loops over the requested branches.
*
* @param out the iterator
* @param[out] out the iterator
* @param repo Repository where to find the branches.
* @param list_flags Filtering flags for the branch
* listing. Valid values are GIT_BRANCH_LOCAL, GIT_BRANCH_REMOTE
@@ -115,12 +115,15 @@ GIT_EXTERN(int) git_branch_iterator_new(
/**
* Retrieve the next branch from the iterator
*
* @param out the reference
* @param[out] out the reference
* @param out_type the type of branch (local or remote-tracking)
* @param iter the branch iterator
* @return 0 on success, GIT_ITEROVER if there are no more branches or an error code.
*/
GIT_EXTERN(int) git_branch_next(git_reference **out, git_branch_t *out_type, git_branch_iterator *iter);
GIT_EXTERN(int) git_branch_next(
git_reference **out,
git_branch_t *out_type,
git_branch_iterator *iter);
/**
* Free a branch iterator
@@ -139,15 +142,11 @@ GIT_EXTERN(void) git_branch_iterator_free(git_branch_iterator *iter);
* be valid anymore, and should be freed immediately by the user using
* `git_reference_free()`.
*
* @param out New reference object for the updated name.
*
* @param[out] out New reference object for the updated name.
* @param branch Current underlying reference of the branch.
*
* @param new_branch_name Target name of the branch once the move
* is performed; this name is validated for consistency.
*
* is performed; this name is validated for consistency.
* @param force Overwrite existing branch.
*
* @return 0 on success, GIT_EINVALIDSPEC or an error code.
*/
GIT_EXTERN(int) git_branch_move(
@@ -164,7 +163,7 @@ GIT_EXTERN(int) git_branch_move(
*
* @see git_tag_create for rules about valid names.
*
* @param out pointer to the looked-up branch reference
* @param[out] out pointer to the looked-up branch reference
* @param repo the repository to look up the branch
* @param branch_name Name of the branch to be looked-up;
* this name is validated for consistency.
@@ -187,13 +186,11 @@ GIT_EXTERN(int) git_branch_lookup(
* it lives under "refs/heads/" or "refs/remotes/"), and return the branch part
* of it.
*
* @param out Pointer to the abbreviated reference name.
* @param[out] out Pointer to the abbreviated reference name.
* Owned by ref, do not free.
*
* @param ref A reference object, ideally pointing to a branch
*
* @return 0 on success; GIT_EINVALID if the reference isn't either a local or
* remote branch, otherwise an error code.
* @return 0 on success; GIT_EINVALID if the reference isn't either a
* local or remote branch, otherwise an error code.
*/
GIT_EXTERN(int) git_branch_name(
const char **out,
@@ -207,9 +204,8 @@ GIT_EXTERN(int) git_branch_name(
*
* @see git_branch_upstream_name for details on the resolution.
*
* @param out Pointer where to store the retrieved reference.
* @param[out] out Pointer where to store the retrieved reference.
* @param branch Current underlying reference of the branch.
*
* @return 0 on success; GIT_ENOTFOUND when no remote tracking
* reference exists, otherwise an error code.
*/

2
include/git2/cherrypick.h
View File

@@ -64,7 +64,7 @@ GIT_EXTERN(int) git_cherrypick_options_init(
*
* The returned index must be freed explicitly with `git_index_free`.
*
* @param out pointer to store the index result in
* @param[out] out pointer to store the index result in
* @param repo the repository that contains the given commits
* @param cherrypick_commit the commit to cherry-pick
* @param our_commit the commit to cherry-pick against (eg, HEAD)

16
include/git2/commit.h
View File

@@ -182,13 +182,15 @@ GIT_EXTERN(const git_signature *) git_commit_author(const git_commit *commit);
*
* Call `git_signature_free` to free the signature.
*
* @param out a pointer to store the resolved signature.
* @param[out] out a pointer to store the resolved signature.
* @param commit a previously loaded commit.
* @param mailmap the mailmap to resolve with. (may be NULL)
* @return 0 or an error code
*/
GIT_EXTERN(int) git_commit_committer_with_mailmap(
git_signature **out, const git_commit *commit, const git_mailmap *mailmap);
git_signature **out,
const git_commit *commit,
const git_mailmap *mailmap);
/**
* Get the author of a commit, using the mailmap to map names and email
@@ -196,13 +198,15 @@ GIT_EXTERN(int) git_commit_committer_with_mailmap(
*
* Call `git_signature_free` to free the signature.
*
* @param out a pointer to store the resolved signature.
* @param[out] out a pointer to store the resolved signature.
* @param commit a previously loaded commit.
* @param mailmap the mailmap to resolve with. (may be NULL)
* @return 0 or an error code
*/
GIT_EXTERN(int) git_commit_author_with_mailmap(
git_signature **out, const git_commit *commit, const git_mailmap *mailmap);
git_signature **out,
const git_commit *commit,
const git_mailmap *mailmap);
/**
* Get the full raw text of the commit header.
@@ -242,7 +246,7 @@ GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit);
/**
* Get the specified parent of the commit.
*
* @param out Pointer where to store the parent commit
* @param[out] out Pointer where to store the parent commit
* @param commit a previously loaded commit.
* @param n the position of the parent (from 0 to `parentcount`)
* @return 0 or an error code
@@ -791,7 +795,7 @@ GIT_EXTERN(int) git_commit_create_with_signature(
* Create an in-memory copy of a commit. The copy must be explicitly
* free'd or it will leak.
*
* @param out Pointer to store the copy of the commit
* @param[out] out Pointer to store the copy of the commit
* @param source Original commit to copy
* @return 0
*/

114
include/git2/config.h
View File

@@ -229,7 +229,7 @@ GIT_EXTERN(int) git_config_find_programdata(git_buf *out);
* and opens them into a single prioritized config object that can be
* used when accessing default config data outside a repository.
*
* @param out Pointer to store the config instance
* @param[out] out Pointer to store the config instance
* @return 0 or an error code
*/
GIT_EXTERN(int) git_config_open_default(git_config **out);
@@ -240,7 +240,7 @@ GIT_EXTERN(int) git_config_open_default(git_config **out);
* This object is empty, so you have to add a file to it before you
* can do anything with it.
*
* @param out pointer to the new configuration
* @param[out] out pointer to the new configuration
* @return 0 or an error code
*/
GIT_EXTERN(int) git_config_new(git_config **out);
@@ -287,7 +287,7 @@ GIT_EXTERN(int) git_config_add_file_ondisk(
* - git_config_new
* - git_config_add_file_ondisk
*
* @param out The configuration instance to create
* @param[out] out The configuration instance to create
* @param path Path to the on-disk file to open
* @return 0 on success, or an error code
*/
@@ -303,7 +303,7 @@ GIT_EXTERN(int) git_config_open_ondisk(git_config **out, const char *path);
* will return different config instances, but containing the same config_file
* instance.
*
* @param out The configuration instance to create
* @param[out] out The configuration instance to create
* @param parent Multi-level config to search for the given level
* @param level Configuration level to search for
* @return 0, GIT_ENOTFOUND if the passed level cannot be found in the
@@ -323,7 +323,7 @@ GIT_EXTERN(int) git_config_open_level(
* created it explicitly. With this function you'll open the correct
* one to write to.
*
* @param out pointer in which to store the config object
* @param[out] out pointer in which to store the config object
* @param config the config object in which to look
* @return 0 or an error code.
*/
@@ -355,7 +355,7 @@ GIT_EXTERN(int) git_config_set_writeorder(
* The string returned when querying such a config object is valid
* until it is freed.
*
* @param out pointer in which to store the snapshot config object
* @param[out] out pointer in which to store the snapshot config object
* @param config configuration to snapshot
* @return 0 or an error code
*/
@@ -373,7 +373,7 @@ GIT_EXTERN(void) git_config_free(git_config *cfg);
*
* Free the git_config_entry after use with `git_config_entry_free()`.
*
* @param out pointer to the variable git_config_entry
* @param[out] out pointer to the variable git_config_entry
* @param cfg where to look for the variable
* @param name the variable's name
* @return 0 or an error code
@@ -390,12 +390,15 @@ GIT_EXTERN(int) git_config_get_entry(
* defined level. A higher level means a higher priority. The
* first occurrence of the variable will be returned here.
*
* @param out pointer to the variable where the value should be stored
* @param[out] out pointer to the variable where the value should be stored
* @param cfg where to look for the variable
* @param name the variable's name
* @return 0 or an error code
*/
GIT_EXTERN(int) git_config_get_int32(int32_t *out, const git_config *cfg, const char *name);
GIT_EXTERN(int) git_config_get_int32(
int32_t *out,
const git_config *cfg,
const char *name);
/**
* Get the value of a long integer config variable.
@@ -404,12 +407,15 @@ GIT_EXTERN(int) git_config_get_int32(int32_t *out, const git_config *cfg, const
* defined level. A higher level means a higher priority. The
* first occurrence of the variable will be returned here.
*
* @param out pointer to the variable where the value should be stored
* @param[out] out pointer to the variable where the value should be stored
* @param cfg where to look for the variable
* @param name the variable's name
* @return 0 or an error code
*/
GIT_EXTERN(int) git_config_get_int64(int64_t *out, const git_config *cfg, const char *name);
GIT_EXTERN(int) git_config_get_int64(
int64_t *out,
const git_config *cfg,
const char *name);
/**
* Get the value of a boolean config variable.
@@ -421,12 +427,15 @@ GIT_EXTERN(int) git_config_get_int64(int64_t *out, const git_config *cfg, const
* defined level. A higher level means a higher priority. The
* first occurrence of the variable will be returned here.
*
* @param out pointer to the variable where the value should be stored
* @param[out] out pointer to the variable where the value should be stored
* @param cfg where to look for the variable
* @param name the variable's name
* @return 0 or an error code
*/
GIT_EXTERN(int) git_config_get_bool(int *out, const git_config *cfg, const char *name);
GIT_EXTERN(int) git_config_get_bool(
int *out,
const git_config *cfg,
const char *name);
/**
* Get the value of a path config variable.
@@ -444,7 +453,10 @@ GIT_EXTERN(int) git_config_get_bool(int *out, const git_config *cfg, const char
* @param name the variable's name
* @return 0 or an error code
*/
GIT_EXTERN(int) git_config_get_path(git_buf *out, const git_config *cfg, const char *name);
GIT_EXTERN(int) git_config_get_path(
git_buf *out,
const git_config *cfg,
const char *name);
/**
* Get the value of a string config variable.
@@ -457,12 +469,15 @@ GIT_EXTERN(int) git_config_get_path(git_buf *out, const git_config *cfg, const c
* defined level. A higher level means a higher priority. The
* first occurrence of the variable will be returned here.
*
* @param out pointer to the string
* @param[out] out pointer to the string
* @param cfg where to look for the variable
* @param name the variable's name
* @return 0 or an error code
*/
GIT_EXTERN(int) git_config_get_string(const char **out, const git_config *cfg, const char *name);
GIT_EXTERN(int) git_config_get_string(
const char **out,
const git_config *cfg,
const char *name);
/**
* Get the value of a string config variable.
@@ -478,7 +493,10 @@ GIT_EXTERN(int) git_config_get_string(const char **out, const git_config *cfg, c
* @param name the variable's name
* @return 0 or an error code
*/
GIT_EXTERN(int) git_config_get_string_buf(git_buf *out, const git_config *cfg, const char *name);
GIT_EXTERN(int) git_config_get_string_buf(
git_buf *out,
const git_config *cfg,
const char *name);
/**
* Get each value of a multivar in a foreach callback
@@ -492,12 +510,17 @@ GIT_EXTERN(int) git_config_get_string_buf(git_buf *out, const git_config *cfg, c
* @param cfg where to look for the variable
* @param name the variable's name
* @param regexp regular expression to filter which variables we're
* interested in. Use NULL to indicate all
* interested in. Use NULL to indicate all
* @param callback the function to be called on each value of the variable
* @param payload opaque pointer to pass to the callback
* @return 0 or an error code.
*/
GIT_EXTERN(int) git_config_get_multivar_foreach(const git_config *cfg, const char *name, const char *regexp, git_config_foreach_cb callback, void *payload);
GIT_EXTERN(int) git_config_get_multivar_foreach(
const git_config *cfg,
const char *name,
const char *regexp,
git_config_foreach_cb callback,
void *payload);
/**
* Get each value of a multivar
@@ -506,14 +529,18 @@ GIT_EXTERN(int) git_config_get_multivar_foreach(const git_config *cfg, const cha
* the variable name: the section and variable parts are lower-cased. The
* subsection is left unchanged.
*
* @param out pointer to store the iterator
* @param[out] out pointer to store the iterator
* @param cfg where to look for the variable
* @param name the variable's name
* @param regexp regular expression to filter which variables we're
* interested in. Use NULL to indicate all
* @return 0 or an error code.
*/
GIT_EXTERN(int) git_config_multivar_iterator_new(git_config_iterator **out, const git_config *cfg, const char *name, const char *regexp);
GIT_EXTERN(int) git_config_multivar_iterator_new(
git_config_iterator **out,
const git_config *cfg,
const char *name,
const char *regexp);
/**
* Return the current entry and advance the iterator
@@ -521,11 +548,13 @@ GIT_EXTERN(int) git_config_multivar_iterator_new(git_config_iterator **out, cons
* The pointers returned by this function are valid until the next call
* to `git_config_next` or until the iterator is freed.
*
* @param entry pointer to store the entry
* @param[out] entry pointer to store the entry
* @param iter the iterator
* @return 0 or an error code. GIT_ITEROVER if the iteration has completed
*/
GIT_EXTERN(int) git_config_next(git_config_entry **entry, git_config_iterator *iter);
GIT_EXTERN(int) git_config_next(
git_config_entry **entry,
git_config_iterator *iter);
/**
* Free a config iterator
@@ -579,7 +608,10 @@ GIT_EXTERN(int) git_config_set_bool(git_config *cfg, const char *name, int value
* @param value the string to store.
* @return 0 or an error code
*/
GIT_EXTERN(int) git_config_set_string(git_config *cfg, const char *name, const char *value);
GIT_EXTERN(int) git_config_set_string(
git_config *cfg,
const char *name,
const char *value);
/**
* Set a multivar in the local config file.
@@ -592,7 +624,11 @@ GIT_EXTERN(int) git_config_set_string(git_config *cfg, const char *name, const c
* @param value the new value.
* @return 0 or an error code.
*/
GIT_EXTERN(int) git_config_set_multivar(git_config *cfg, const char *name, const char *regexp, const char *value);
GIT_EXTERN(int) git_config_set_multivar(
git_config *cfg,
const char *name,
const char *regexp,
const char *value);
/**
* Delete a config variable from the config file
@@ -615,7 +651,10 @@ GIT_EXTERN(int) git_config_delete_entry(git_config *cfg, const char *name);
*
* @return 0 or an error code
*/
GIT_EXTERN(int) git_config_delete_multivar(git_config *cfg, const char *name, const char *regexp);
GIT_EXTERN(int) git_config_delete_multivar(
git_config *cfg,
const char *name,
const char *regexp);
/**
* Perform an operation on each config variable.
@@ -644,11 +683,13 @@ GIT_EXTERN(int) git_config_foreach(
* Use `git_config_next` to advance the iteration and
* `git_config_iterator_free` when done.
*
* @param out pointer to store the iterator
* @param[out] out pointer to store the iterator
* @param cfg where to get the variables from
* @return 0 or an error code.
*/
GIT_EXTERN(int) git_config_iterator_new(git_config_iterator **out, const git_config *cfg);
GIT_EXTERN(int) git_config_iterator_new(
git_config_iterator **out,
const git_config *cfg);
/**
* Iterate over all the config variables whose name matches a pattern
@@ -660,12 +701,15 @@ GIT_EXTERN(int) git_config_iterator_new(git_config_iterator **out, const git_con
* the variable name: the section and variable parts are lower-cased. The
* subsection is left unchanged.
*
* @param out pointer to store the iterator
* @param[out] out pointer to store the iterator
* @param cfg where to ge the variables from
* @param regexp regular expression to match the names
* @return 0 or an error code.
*/
GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator **out, const git_config *cfg, const char *regexp);
GIT_EXTERN(int) git_config_iterator_glob_new(
git_config_iterator **out,
const git_config *cfg,
const char *regexp);
/**
* Perform an operation on each config variable matching a regular expression.
@@ -720,7 +764,7 @@ GIT_EXTERN(int) git_config_foreach_match(
* If not a single match can be made to store in `out`, an error code will be
* returned.
*
* @param out place to store the result of the mapping
* @param[out] out place to store the result of the mapping
* @param cfg config file to get the variables from
* @param name name of the config variable to lookup
* @param maps array of `git_configmap` objects specifying the possible mappings
@@ -737,7 +781,7 @@ GIT_EXTERN(int) git_config_get_mapped(
/**
* Maps a string value to an integer constant
*
* @param out place to store the result of the parsing
* @param[out] out place to store the result of the parsing
* @param maps array of `git_configmap` objects specifying the possible mappings
* @param map_n number of mapping objects in `maps`
* @param value value to parse
@@ -756,7 +800,7 @@ GIT_EXTERN(int) git_config_lookup_map_value(
* number different from 0
* Valid values for false are: 'false', 'no', 'off', 0
*
* @param out place to store the result of the parsing
* @param[out] out place to store the result of the parsing
* @param value value to parse
* @return 0 or an error code.
*/
@@ -769,7 +813,7 @@ GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value);
* cause the value to be multiplied by 1024, 1048576,
* or 1073741824 prior to output.
*
* @param out place to store the result of the parsing
* @param[out] out place to store the result of the parsing
* @param value value to parse
* @return 0 or an error code.
*/
@@ -782,7 +826,7 @@ GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value);
* cause the value to be multiplied by 1024, 1048576,
* or 1073741824 prior to output.
*
* @param out place to store the result of the parsing
* @param[out] out place to store the result of the parsing
* @param value value to parse
* @return 0 or an error code.
*/

20
include/git2/credential.h
View File

@@ -168,7 +168,7 @@ GIT_EXTERN(const char *) git_credential_get_username(git_credential *cred);
* Create a new plain-text username and password credential object.
* The supplied credential parameter will be internally duplicated.
*
* @param out The newly created credential object.
* @param[out] out The newly created credential object.
* @param username The username of the credential.
* @param password The password of the credential.
* @return 0 for success or an error code for failure
@@ -182,7 +182,7 @@ GIT_EXTERN(int) git_credential_userpass_plaintext_new(
* Create a "default" credential usable for Negotiate mechanisms like NTLM
* or Kerberos authentication.
*
* @param out The newly created credential object.
* @param[out] out The newly created credential object.
* @return 0 for success or an error code for failure
*/
GIT_EXTERN(int) git_credential_default_new(git_credential **out);
@@ -193,7 +193,7 @@ GIT_EXTERN(int) git_credential_default_new(git_credential **out);
* This is used with ssh authentication to query for the username if
* none is specified in the url.
*
* @param out The newly created credential object.
* @param[out] out The newly created credential object.
* @param username The username to authenticate with
* @return 0 for success or an error code for failure
*/
@@ -203,7 +203,7 @@ GIT_EXTERN(int) git_credential_username_new(git_credential **out, const char *us
* Create a new passphrase-protected ssh key credential object.
* The supplied credential parameter will be internally duplicated.
*
* @param out The newly created credential object.
* @param[out] out The newly created credential object.
* @param username username to use to authenticate
* @param publickey The path to the public key of the credential.
* @param privatekey The path to the private key of the credential.
@@ -220,7 +220,7 @@ GIT_EXTERN(int) git_credential_ssh_key_new(
/**
* Create a new ssh key credential object reading the keys from memory.
*
* @param out The newly created credential object.
* @param[out] out The newly created credential object.
* @param username username to use to authenticate.
* @param publickey The public key of the credential.
* @param privatekey The private key of the credential.
@@ -269,7 +269,7 @@ typedef void GIT_CALLBACK(git_credential_ssh_interactive_cb)(
* Create a new ssh keyboard-interactive based credential object.
* The supplied credential parameter will be internally duplicated.
*
* @param out The newly created credential object.
* @param[out] out The newly created credential object.
* @param username Username to use to authenticate.
* @param prompt_callback The callback method used for prompts.
* @param payload Additional data to pass to the callback.
@@ -285,7 +285,7 @@ GIT_EXTERN(int) git_credential_ssh_interactive_new(
* Create a new ssh key credential object used for querying an ssh-agent.
* The supplied credential parameter will be internally duplicated.
*
* @param out The newly created credential object.
* @param[out] out The newly created credential object.
* @param username username to use to authenticate
* @return 0 for success or an error code for failure
*/
@@ -297,8 +297,8 @@ GIT_EXTERN(int) git_credential_ssh_key_from_agent(
* Callback for credential signing.
*
* @param session the libssh2 session
* @param sig the signature
* @param sig_len the length of the signature
* @param[out] sig the signature
* @param[out] sig_len the length of the signature
* @param data the data
* @param data_len the length of the data
* @param abstract the abstract
@@ -321,7 +321,7 @@ typedef int GIT_CALLBACK(git_credential_sign_cb)(
*
* The supplied credential parameter will be internally duplicated.
*
* @param out The newly created credential object.
* @param[out] out The newly created credential object.
* @param username username to use to authenticate
* @param publickey The bytes of the public key.
* @param publickey_len The length of the public key in bytes.

2
include/git2/credential_helpers.h
View File

@@ -32,7 +32,7 @@ typedef struct git_credential_userpass_payload {
* git_cred_userpass_plaintext_new unless the protocol has not specified
* `GIT_CREDENTIAL_USERPASS_PLAINTEXT` as an allowed type.
*
* @param out The newly created credential object.
* @param[out] out The newly created credential object.
* @param url The resource for which we are demanding a credential.
* @param user_from_url The username that was embedded in a "user\@host"
* remote url, or NULL if not included.

4
include/git2/describe.h
View File

@@ -150,7 +150,7 @@ typedef struct git_describe_result git_describe_result;
*
* Perform the describe operation on the given committish object.
*
* @param result pointer to store the result. You must free this once
* @param[out] result pointer to store the result. You must free this once
* you're done with it.
* @param committish a committish to describe
* @param opts the lookup options (or NULL for defaults)
@@ -168,7 +168,7 @@ GIT_EXTERN(int) git_describe_commit(
* worktree. After performing describe on HEAD, a status is run and the
* description is considered to be dirty if there are.
*
* @param out pointer to store the result. You must free this once
* @param[out] out pointer to store the result. You must free this once
* you're done with it.
* @param repo the repository in which to perform the describe
* @param opts the lookup options (or NULL for defaults)

7
include/git2/diff.h
View File

@@ -379,6 +379,9 @@ typedef int GIT_CALLBACK(git_diff_progress_cb)(
* values. Similarly, passing NULL for the options structure will
* give the defaults. The default values are marked below.
*
* @options[version] GIT_DIFF_OPTIONS_VERSION
* @options[init_macro] GIT_DIFF_OPTIONS_INIT
* @options[init_function] git_diff_options_init
*/
typedef struct {
unsigned int version; /**< version for the struct */
@@ -1351,7 +1354,7 @@ typedef struct {
* @note This API only supports SHA1 patch files
* @see git_diff_from_buffer_ext
*
* @param out A pointer to a git_diff pointer that will be allocated.
* @param[out] out A pointer to a git_diff pointer that will be allocated.
* @param content The contents of a patch file
* @param content_len The length of the patch file contents
* @return 0 or an error code
@@ -1421,7 +1424,7 @@ typedef enum {
/**
* Accumulate diff statistics for all patches.
*
* @param out Structure containing the diff statistics.
* @param[out] out Structure containing the diff statistics.
* @param diff A git_diff generated by one of the above functions.
* @return 0 on success; non-zero on error
*/

11
include/git2/graph.h
View File

@@ -28,14 +28,19 @@ GIT_BEGIN_DECL
* the other as its upstream, the `ahead` and `behind` values will be
* what git would report for the branches.
*
* @param ahead number of unique from commits in `upstream`
* @param behind number of unique from commits in `local`
* @param[out] ahead number of unique from commits in `upstream`
* @param[out] behind number of unique from commits in `local`
* @param repo the repository where the commits exist
* @param local the commit for local
* @param upstream the commit for upstream
* @return 0 or an error code.
*/
GIT_EXTERN(int) git_graph_ahead_behind(size_t *ahead, size_t *behind, git_repository *repo, const git_oid *local, const git_oid *upstream);
GIT_EXTERN(int) git_graph_ahead_behind(
size_t *ahead,
size_t *behind,
git_repository *repo,
const git_oid *local,
const git_oid *upstream);
/**

18
include/git2/index.h
View File

@@ -608,7 +608,7 @@ GIT_EXTERN(int) git_index_iterator_new(
/**
* Return the next index entry in-order from the iterator.
*
* @param out Pointer to store the index entry in
* @param[out] out Pointer to store the index entry in
* @param iterator The iterator
* @return 0, GIT_ITEROVER on iteration completion or an error code
*/
@@ -808,23 +808,31 @@ GIT_EXTERN(int) git_index_update_all(
* Find the first position of any entries which point to given
* path in the Git index.
*
* @param at_pos the address to which the position of the index entry is written (optional)
* @param[out] at_pos the address to which the position of the
* index entry is written (optional)
* @param index an existing index object
* @param path path to search
* @return 0 or an error code
*/
GIT_EXTERN(int) git_index_find(size_t *at_pos, git_index *index, const char *path);
GIT_EXTERN(int) git_index_find(
size_t *at_pos,
git_index *index,
const char *path);
/**
* Find the first position of any entries matching a prefix. To find the first position
* of a path inside a given folder, suffix the prefix with a '/'.
*
* @param at_pos the address to which the position of the index entry is written (optional)
* @param[out] at_pos the address to which the position of the
* index entry is written (optional)
* @param index an existing index object
* @param prefix the prefix to search for
* @return 0 or an error code
*/
GIT_EXTERN(int) git_index_find_prefix(size_t *at_pos, git_index *index, const char *prefix);
GIT_EXTERN(int) git_index_find_prefix(
size_t *at_pos,
git_index *index,
const char *prefix);
/**@}*/

2
include/git2/indexer.h
View File

@@ -134,7 +134,7 @@ GIT_EXTERN(int) git_indexer_new(
/**
* Create a new indexer instance
*
* @param out where to store the indexer instance
* @param[out] out where to store the indexer instance
* @param path to the directory where the packfile should be stored
* @param mode permissions to use creating packfile or 0 for defaults
* @param odb object database from which to read base objects when

12
include/git2/mailmap.h
View File

@@ -31,7 +31,7 @@ GIT_BEGIN_DECL
* This object is empty, so you'll have to add a mailmap file before you can do
* anything with it. The mailmap must be freed with 'git_mailmap_free'.
*
* @param out pointer to store the new mailmap
* @param[out] out pointer to store the new mailmap
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_mailmap_new(git_mailmap **out);
@@ -61,7 +61,7 @@ GIT_EXTERN(int) git_mailmap_add_entry(
/**
* Create a new mailmap instance containing a single mailmap file
*
* @param out pointer to store the new mailmap
* @param[out] out pointer to store the new mailmap
* @param buf buffer to parse the mailmap from
* @param len the length of the input buffer
* @return 0 on success, or an error code
@@ -79,7 +79,7 @@ GIT_EXTERN(int) git_mailmap_from_buffer(
* [NOTE: 'mailmap.blob' defaults to 'HEAD:.mailmap' in bare repositories]
* 3. The path in the 'mailmap.file' config entry, if set.
*
* @param out pointer to store the new mailmap
* @param[out] out pointer to store the new mailmap
* @param repo repository to load mailmap information from
* @return 0 on success, or an error code
*/
@@ -91,8 +91,8 @@ GIT_EXTERN(int) git_mailmap_from_repository(
*
* The lifetime of the strings are tied to `mm`, `name`, and `email` parameters.
*
* @param real_name pointer to store the real name
* @param real_email pointer to store the real email
* @param[out] real_name pointer to store the real name
* @param[out] real_email pointer to store the real email
* @param mm the mailmap to perform a lookup with (may be NULL)
* @param name the name to look up
* @param email the email to look up
@@ -107,7 +107,7 @@ GIT_EXTERN(int) git_mailmap_resolve(
*
* Call `git_signature_free()` to free the data.
*
* @param out new signature
* @param[out] out new signature
* @param mm mailmap to resolve with
* @param sig signature to resolve
* @return 0 or an error code

4
include/git2/merge.h
View File

@@ -604,7 +604,7 @@ GIT_EXTERN(void) git_merge_file_result_free(git_merge_file_result *result);
*
* The returned index must be freed explicitly with `git_index_free`.
*
* @param out pointer to store the index result in
* @param[out] out pointer to store the index result in
* @param repo repository that contains the given trees
* @param ancestor_tree the common ancestor between the trees (or null if none)
* @param our_tree the tree that reflects the destination tree
@@ -628,7 +628,7 @@ GIT_EXTERN(int) git_merge_trees(
*
* The returned index must be freed explicitly with `git_index_free`.
*
* @param out pointer to store the index result in
* @param[out] out pointer to store the index result in
* @param repo repository that contains the given trees
* @param our_commit the commit that reflects the destination tree
* @param their_commit the commit to merge in to `our_commit`

8
include/git2/notes.h
View File

@@ -42,7 +42,7 @@ typedef struct git_iterator git_note_iterator;
*
* The iterator must be freed manually by the user.
*
* @param out pointer to the iterator
* @param[out] out pointer to the iterator
* @param repo repository where to look up the note
* @param notes_ref canonical name of the reference to use (optional); defaults to
* "refs/notes/commits"
@@ -59,7 +59,7 @@ GIT_EXTERN(int) git_note_iterator_new(
*
* The iterator must be freed manually by the user.
*
* @param out pointer to the iterator
* @param[out] out pointer to the iterator
* @param notes_commit a pointer to the notes commit object
*
* @return 0 or an error code
@@ -97,7 +97,7 @@ GIT_EXTERN(int) git_note_next(
*
* The note must be freed manually by the user.
*
* @param out pointer to the read note; NULL in case of error
* @param[out] out pointer to the read note; NULL in case of error
* @param repo repository where to look up the note
* @param notes_ref canonical name of the reference to use (optional); defaults to
* "refs/notes/commits"
@@ -117,7 +117,7 @@ GIT_EXTERN(int) git_note_read(
*
* The note must be freed manually by the user.
*
* @param out pointer to the read note; NULL in case of error
* @param[out] out pointer to the read note; NULL in case of error
* @param repo repository where to look up the note
* @param notes_commit a pointer to the notes commit object
* @param oid OID of the git object to read the note from

4
include/git2/object.h
View File

@@ -87,8 +87,8 @@ GIT_EXTERN(int) git_object_lookup_prefix(
/**
* Lookup an object that represents a tree entry.
*
* @param out buffer that receives a pointer to the object (which must be freed
* by the caller)
* @param[out] out buffer that receives a pointer to the object
* (which must be freed by the caller)
* @param treeish root object that can be peeled to a tree
* @param path relative path from the root object to the desired object
* @param type type of object desired

16
include/git2/odb.h
View File

@@ -372,13 +372,17 @@ GIT_EXTERN(int) git_odb_write(git_oid *out, git_odb *odb, const void *data, size
*
* @see git_odb_stream
*
* @param out pointer where to store the stream
* @param[out] out pointer where to store the stream
* @param db object database where the stream will write
* @param size final size of the object that will be written
* @param type type of the object that will be written
* @return 0 if the stream was created; error code otherwise
*/
GIT_EXTERN(int) git_odb_open_wstream(git_odb_stream **out, git_odb *db, git_object_size_t size, git_object_t type);
GIT_EXTERN(int) git_odb_open_wstream(
git_odb_stream **out,
git_odb *db,
git_object_size_t size,
git_object_t type);
/**
* Write to an odb stream
@@ -446,8 +450,8 @@ GIT_EXTERN(void) git_odb_stream_free(git_odb_stream *stream);
*
* @see git_odb_stream
*
* @param out pointer where to store the stream
* @param len pointer where to store the length of the object
* @param[out] out pointer where to store the stream
* @param[out] len pointer where to store the length of the object
* @param type pointer where to store the type of the object
* @param db object database where the stream will read from
* @param oid oid of the object the stream will read from
@@ -471,7 +475,7 @@ GIT_EXTERN(int) git_odb_open_rstream(
*
* @see git_odb_writepack
*
* @param out pointer to the writepack functions
* @param[out] out pointer to the writepack functions
* @param db object database where the stream will read from
* @param progress_cb function to call with progress information.
* Be aware that this is called inline with network and indexing operations,
@@ -613,7 +617,7 @@ GIT_EXTERN(size_t) git_odb_num_backends(git_odb *odb);
/**
* Lookup an ODB backend object by index
*
* @param out output pointer to ODB backend at pos
* @param[out] out output pointer to ODB backend at pos
* @param odb object database
* @param pos index into object database backend list
* @return 0 on success, GIT_ENOTFOUND if pos is invalid, other errors < 0

2
include/git2/pack.h
View File

@@ -57,7 +57,7 @@ typedef enum {
/**
* Initialize a new packbuilder
*
* @param out The new packbuilder object
* @param[out] out The new packbuilder object
* @param repo The repository
*
* @return 0 or an error code

20
include/git2/patch.h
View File

@@ -51,7 +51,7 @@ GIT_EXTERN(git_repository *) git_patch_owner(const git_patch *patch);
* It is okay to pass NULL for either of the output parameters; if you pass
* NULL for the `git_patch`, then the text diff will not be calculated.
*
* @param out Output parameter for the delta patch object
* @param[out] out Output parameter for the delta patch object
* @param diff Diff list object
* @param idx Index into diff list
* @return 0 on success, other value < 0 on error
@@ -67,7 +67,7 @@ GIT_EXTERN(int) git_patch_from_diff(
* standard `git_patch` accessor functions to read the patch data, and
* you must call `git_patch_free()` on the patch when done.
*
* @param out The generated patch; NULL on error
* @param[out] out The generated patch; NULL on error
* @param old_blob Blob for old side of diff, or NULL for empty blob
* @param old_as_path Treat old blob as if it had this filename; can be NULL
* @param new_blob Blob for new side of diff, or NULL for empty blob
@@ -91,7 +91,7 @@ GIT_EXTERN(int) git_patch_from_blobs(
* use the standard `git_patch` accessor functions to read the patch
* data, and you must call `git_patch_free()` on the patch when done.
*
* @param out The generated patch; NULL on error
* @param[out] out The generated patch; NULL on error
* @param old_blob Blob for old side of diff, or NULL for empty blob
* @param old_as_path Treat old blob as if it had this filename; can be NULL
* @param buffer Raw data for new side of diff, or NULL for empty
@@ -117,7 +117,7 @@ GIT_EXTERN(int) git_patch_from_blob_and_buffer(
* use the standard `git_patch` accessor functions to read the patch
* data, and you must call `git_patch_free()` on the patch when done.
*
* @param out The generated patch; NULL on error
* @param[out] out The generated patch; NULL on error
* @param old_buffer Raw data for old side of diff, or NULL for empty
* @param old_len Length of the raw data for old side of the diff
* @param old_as_path Treat old buffer as if it had this filename; can be NULL
@@ -171,9 +171,9 @@ GIT_EXTERN(size_t) git_patch_num_hunks(const git_patch *patch);
*
* All outputs are optional. Pass NULL if you don't need a particular count.
*
* @param total_context Count of context lines in output, can be NULL.
* @param total_additions Count of addition lines in output, can be NULL.
* @param total_deletions Count of deletion lines in output, can be NULL.
* @param[out] total_context Count of context lines in output, can be NULL.
* @param[out] total_additions Count of addition lines in output, can be NULL.
* @param[out] total_deletions Count of deletion lines in output, can be NULL.
* @param patch The git_patch object
* @return 0 on success, <0 on error
*/
@@ -190,8 +190,8 @@ GIT_EXTERN(int) git_patch_line_stats(
* information about that hunk. Any of the output pointers can be passed
* as NULL if you don't care about that particular piece of information.
*
* @param out Output pointer to git_diff_hunk of hunk
* @param lines_in_hunk Output count of total lines in this hunk
* @param[out] out Output pointer to git_diff_hunk of hunk
* @param[out] lines_in_hunk Output count of total lines in this hunk
* @param patch Input pointer to patch object
* @param hunk_idx Input index of hunk to get information about
* @return 0 on success, GIT_ENOTFOUND if hunk_idx out of range, <0 on error
@@ -221,7 +221,7 @@ GIT_EXTERN(int) git_patch_num_lines_in_hunk(
* index larger than the number of hunks or a line index larger than
* the number of lines in the hunk, this will return -1.
*
* @param out The git_diff_line data for this line
* @param[out] out The git_diff_line data for this line
* @param patch The patch to look in
* @param hunk_idx The index of the hunk
* @param line_of_hunk The index of the line in the hunk

10
include/git2/pathspec.h
View File

@@ -82,7 +82,7 @@ typedef enum {
/**
* Compile a pathspec
*
* @param out Output of the compiled pathspec
* @param[out] out Output of the compiled pathspec
* @param pathspec A git_strarray of the paths to match
* @return 0 on success, <0 on failure
*/
@@ -127,7 +127,7 @@ GIT_EXTERN(int) git_pathspec_matches_path(
* pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES`
* flag). You must call `git_pathspec_match_list_free()` on this object.
*
* @param out Output list of matches; pass NULL to just get return value
* @param[out] out Output list of matches; pass NULL to just get return value
* @param repo The repository in which to match; bare repo is an error
* @param flags Combination of git_pathspec_flag_t options to control match
* @param ps Pathspec to be matched
@@ -156,7 +156,7 @@ GIT_EXTERN(int) git_pathspec_match_workdir(
* pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES`
* flag). You must call `git_pathspec_match_list_free()` on this object.
*
* @param out Output list of matches; pass NULL to just get return value
* @param[out] out Output list of matches; pass NULL to just get return value
* @param index The index to match against
* @param flags Combination of git_pathspec_flag_t options to control match
* @param ps Pathspec to be matched
@@ -180,7 +180,7 @@ GIT_EXTERN(int) git_pathspec_match_index(
* pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES`
* flag). You must call `git_pathspec_match_list_free()` on this object.
*
* @param out Output list of matches; pass NULL to just get return value
* @param[out] out Output list of matches; pass NULL to just get return value
* @param tree The root-level tree to match against
* @param flags Combination of git_pathspec_flag_t options to control match
* @param ps Pathspec to be matched
@@ -204,7 +204,7 @@ GIT_EXTERN(int) git_pathspec_match_tree(
* pathspecs with no match (if you used the `GIT_PATHSPEC_FIND_FAILURES`
* flag). You must call `git_pathspec_match_list_free()` on this object.
*
* @param out Output list of matches; pass NULL to just get return value
* @param[out] out Output list of matches; pass NULL to just get return value
* @param diff A generated diff list
* @param flags Combination of git_pathspec_flag_t options to control match
* @param ps Pathspec to be matched

4
include/git2/rebase.h
View File

@@ -208,7 +208,7 @@ GIT_EXTERN(int) git_rebase_options_init(
* process, call `git_rebase_next`. When you have finished with this
* object, call `git_rebase_free`.
*
* @param out Pointer to store the rebase object
* @param[out] out Pointer to store the rebase object
* @param repo The repository to perform the rebase
* @param branch The terminal commit to rebase, or NULL to rebase the
* current branch
@@ -231,7 +231,7 @@ GIT_EXTERN(int) git_rebase_init(
* Opens an existing rebase that was previously started by either an
* invocation of `git_rebase_init` or by another client.
*
* @param out Pointer to store the rebase object
* @param[out] out Pointer to store the rebase object
* @param repo The repository that has a rebase in-progress
* @param opts Options to specify how rebase is performed
* @return Zero on success; -1 on failure.

8
include/git2/refdb.h
View File

@@ -33,8 +33,8 @@ typedef enum {
* Before the Ref DB can be used for read/writing, a custom database
* backend must be manually set using `git_refdb_set_backend()`
*
* @param out location to store the database pointer, if opened.
* Set to NULL if the open failed.
* @param[out] out location to store the database pointer, if opened.
* Set to NULL if the open failed.
* @param repo the repository
* @return 0 or an error code
*/
@@ -47,8 +47,8 @@ GIT_EXTERN(int) git_refdb_new(git_refdb **out, git_repository *repo);
* - git_refdb_dir: read and write loose and packed refs
* from disk, assuming the repository dir as the folder
*
* @param out location to store the database pointer, if opened.
* Set to NULL if the open failed.
* @param[out] out location to store the database pointer, if opened.
* Set to NULL if the open failed.
* @param repo the repository
* @return 0 or an error code
*/

2
include/git2/reflog.h
View File

@@ -30,7 +30,7 @@ GIT_BEGIN_DECL
* The reflog must be freed manually by using
* git_reflog_free().
*
* @param out pointer to reflog
* @param[out] out pointer to reflog
* @param repo the repository
* @param name reference to look up
* @return 0 or an error code

65
include/git2/refs.h
View File

@@ -60,12 +60,15 @@ GIT_EXTERN(int) git_reference_name_to_id(
* Apply the git precedence rules to the given shorthand to determine
* which reference the user is referring to.
*
* @param out pointer in which to store the reference
* @param[out] out pointer in which to store the reference
* @param repo the repository in which to look
* @param shorthand the short name for the reference
* @return 0 or an error code
*/
GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, const char *shorthand);
GIT_EXTERN(int) git_reference_dwim(
git_reference **out,
git_repository *repo,
const char *shorthand);
/**
* Conditionally create a new symbolic reference.
@@ -100,7 +103,7 @@ GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, co
* If `current_value` is all zeros, this function will return GIT_EMODIFIED
* if the ref already exists.
*
* @param out Pointer to the newly created reference
* @param[out] out Pointer to the newly created reference
* @param repo Repository where that reference will live
* @param name The name of the reference
* @param target The target of the reference
@@ -109,7 +112,14 @@ GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, co
* @param log_message The one line long message to be appended to the reflog
* @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC, GIT_EMODIFIED or an error code
*/
GIT_EXTERN(int) git_reference_symbolic_create_matching(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *current_value, const char *log_message);
GIT_EXTERN(int) git_reference_symbolic_create_matching(
git_reference **out,
git_repository *repo,
const char *name,
const char *target,
int force,
const char *current_value,
const char *log_message);
/**
* Create a new symbolic reference.
@@ -137,7 +147,7 @@ GIT_EXTERN(int) git_reference_symbolic_create_matching(git_reference **out, git_
* not belong in the standard set (HEAD, branches and remote-tracking
* branches) and it does not have a reflog.
*
* @param out Pointer to the newly created reference
* @param[out] out Pointer to the newly created reference
* @param repo Repository where that reference will live
* @param name The name of the reference
* @param target The target of the reference
@@ -145,7 +155,13 @@ GIT_EXTERN(int) git_reference_symbolic_create_matching(git_reference **out, git_
* @param log_message The one line long message to be appended to the reflog
* @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
*/
GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *log_message);
GIT_EXTERN(int) git_reference_symbolic_create(
git_reference **out,
git_repository *repo,
const char *name,
const char *target,
int force,
const char *log_message);
/**
* Create a new direct reference.
@@ -174,7 +190,7 @@ GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repositor
* not belong in the standard set (HEAD, branches and remote-tracking
* branches) and it does not have a reflog.
*
* @param out Pointer to the newly created reference
* @param[out] out Pointer to the newly created reference
* @param repo Repository where that reference will live
* @param name The name of the reference
* @param id The object id pointed to by the reference.
@@ -182,7 +198,13 @@ GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repositor
* @param log_message The one line long message to be appended to the reflog
* @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
*/
GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const char *log_message);
GIT_EXTERN(int) git_reference_create(
git_reference **out,
git_repository *repo,
const char *name,
const git_oid *id,
int force,
const char *log_message);
/**
* Conditionally create new direct reference
@@ -215,7 +237,7 @@ GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo,
* of updating does not match the one passed through `current_id`
* (i.e. if the ref has changed since the user read it).
*
* @param out Pointer to the newly created reference
* @param[out] out Pointer to the newly created reference
* @param repo Repository where that reference will live
* @param name The name of the reference
* @param id The object id pointed to by the reference.
@@ -225,7 +247,14 @@ GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo,
* @return 0 on success, GIT_EMODIFIED if the value of the reference
* has changed, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
*/
GIT_EXTERN(int) git_reference_create_matching(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const git_oid *current_id, const char *log_message);
GIT_EXTERN(int) git_reference_create_matching(
git_reference **out,
git_repository *repo,
const char *name,
const git_oid *id,
int force,
const git_oid *current_id,
const char *log_message);
/**
* Get the OID pointed to by a direct reference.
@@ -295,11 +324,13 @@ GIT_EXTERN(const char *) git_reference_name(const git_reference *ref);
* If a direct reference is passed as an argument, a copy of that
* reference is returned. This copy must be manually freed too.
*
* @param out Pointer to the peeled reference
* @param[out] out Pointer to the peeled reference
* @param ref The reference
* @return 0 or an error code
*/
GIT_EXTERN(int) git_reference_resolve(git_reference **out, const git_reference *ref);
GIT_EXTERN(int) git_reference_resolve(
git_reference **out,
const git_reference *ref);
/**
* Get the repository where a reference resides.
@@ -323,7 +354,7 @@ GIT_EXTERN(git_repository *) git_reference_owner(const git_reference *ref);
* not belong in the standard set (HEAD, branches and remote-tracking
* branches) and it does not have a reflog.
*
* @param out Pointer to the newly created reference
* @param[out] out Pointer to the newly created reference
* @param ref The reference
* @param target The new target for the reference
* @param log_message The one line long message to be appended to the reflog
@@ -342,7 +373,7 @@ GIT_EXTERN(int) git_reference_symbolic_set_target(
*
* The new reference will be written to disk, overwriting the given reference.
*
* @param out Pointer to the newly created reference
* @param[out] out Pointer to the newly created reference
* @param ref The reference
* @param id The new target OID for the reference
* @param log_message The one line long message to be appended to the reflog
@@ -532,7 +563,7 @@ GIT_EXTERN(int) git_reference_iterator_new(
* Create an iterator for the repo's references that match the
* specified glob
*
* @param out pointer in which to store the iterator
* @param[out] out pointer in which to store the iterator
* @param repo the repository
* @param glob the glob to match against the reference names
* @return 0 or an error code
@@ -549,7 +580,9 @@ GIT_EXTERN(int) git_reference_iterator_glob_new(
* @param iter the iterator
* @return 0, GIT_ITEROVER if there are no more; or an error code
*/
GIT_EXTERN(int) git_reference_next(git_reference **out, git_reference_iterator *iter);
GIT_EXTERN(int) git_reference_next(
git_reference **out,
git_reference_iterator *iter);
/**
* Get the next reference's name

26
include/git2/remote.h
View File

@@ -29,7 +29,7 @@ GIT_BEGIN_DECL
/**
* Add a remote with the default fetch refspec to the repository's configuration.
*
* @param out the resulting remote
* @param[out] out the resulting remote
* @param repo the repository in which to create the remote
* @param name the remote's name
* @param url the remote's url
@@ -143,7 +143,7 @@ GIT_EXTERN(int) git_remote_create_options_init(
*
* Passing NULL as the opts argument will result in a detached remote.
*
* @param out the resulting remote
* @param[out] out the resulting remote
* @param url the remote's url
* @param opts the remote creation options
* @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
@@ -157,7 +157,7 @@ GIT_EXTERN(int) git_remote_create_with_opts(
* Add a remote with the provided fetch refspec (or default if NULL) to the repository's
* configuration.
*
* @param out the resulting remote
* @param[out] out the resulting remote
* @param repo the repository in which to create the remote
* @param name the remote's name
* @param url the remote's url
@@ -177,7 +177,7 @@ GIT_EXTERN(int) git_remote_create_with_fetchspec(
* Create a remote with the given url in-memory. You can use this when
* you have a URL instead of a remote's name.
*
* @param out pointer to the new remote objects
* @param[out] out pointer to the new remote objects
* @param repo the associated repository
* @param url the remote repository's URL
* @return 0 or an error code
@@ -197,7 +197,7 @@ GIT_EXTERN(int) git_remote_create_anonymous(
* will not consider any repo configuration values (such as insteadof url
* substitutions).
*
* @param out pointer to the new remote objects
* @param[out] out pointer to the new remote objects
* @param url the remote repository's URL
* @return 0 or an error code
*/
@@ -211,12 +211,15 @@ GIT_EXTERN(int) git_remote_create_detached(
* The name will be checked for validity.
* See `git_tag_create()` for rules about valid names.
*
* @param out pointer to the new remote object
* @param[out] out pointer to the new remote object
* @param repo the associated repository
* @param name the remote's name
* @return 0, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code
*/
GIT_EXTERN(int) git_remote_lookup(git_remote **out, git_repository *repo, const char *name);
GIT_EXTERN(int) git_remote_lookup(
git_remote **out,
git_repository *repo,
const char *name);
/**
* Create a copy of an existing remote. All internal strings are also
@@ -399,12 +402,15 @@ GIT_EXTERN(const git_refspec *)git_remote_get_refspec(const git_remote *remote,
* as a new connection is not initiated, but it is recommended that
* you make a copy in order to make use of the data.
*
* @param out pointer to the array
* @param size the number of remote heads
* @param[out] out pointer to the array
* @param[out] size the number of remote heads
* @param remote the remote
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_remote_ls(const git_remote_head ***out, size_t *size, git_remote *remote);
GIT_EXTERN(int) git_remote_ls(
const git_remote_head ***out,
size_t *size,
git_remote *remote);
/**
* Check whether the remote is connected

28
include/git2/repository.h
View File

@@ -48,11 +48,13 @@ GIT_EXTERN(int) git_repository_open(git_repository **out, const char *path);
* Open the working directory of the working tree as a normal
* repository that can then be worked on.
*
* @param out Output pointer containing opened repository
* @param[out] out Output pointer containing opened repository
* @param wt Working tree to open
* @return 0 or an error code
*/
GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_worktree *wt);
GIT_EXTERN(int) git_repository_open_from_worktree(
git_repository **out,
git_worktree *wt);
/**
* Create a "fake" repository to wrap an object database
@@ -61,7 +63,7 @@ GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_work
* with the API when all you have is an object database. This doesn't
* have any paths associated with it, so use with care.
*
* @param out pointer to the repo
* @param[out] out pointer to the repo
* @param odb the object database to wrap
* @return 0 or an error code
*/
@@ -418,7 +420,7 @@ GIT_EXTERN(int) git_repository_init_options_init(
* `git_libgit2_init` before any APIs can be called, including
* this one.
*
* @param out Pointer to the repo which will be created or reinitialized.
* @param[out] out Pointer to the repo which will be created or reinitialized.
* @param repo_path The path to the repository.
* @param opts Pointer to git_repository_init_options struct.
* @return 0 or an error code on failure.
@@ -446,12 +448,14 @@ GIT_EXTERN(int) git_repository_head(git_reference **out, git_repository *repo);
/**
* Retrieve the referenced HEAD for the worktree
*
* @param out pointer to the reference which will be retrieved
* @param[out] out pointer to the reference which will be retrieved
* @param repo a repository object
* @param name name of the worktree to retrieve HEAD for
* @return 0 when successful, error-code otherwise
*/
GIT_EXTERN(int) git_repository_head_for_worktree(git_reference **out, git_repository *repo,
GIT_EXTERN(int) git_repository_head_for_worktree(
git_reference **out,
git_repository *repo,
const char *name);
/**
@@ -624,11 +628,13 @@ GIT_EXTERN(int) git_repository_is_worktree(const git_repository *repo);
* The configuration file must be freed once it's no longer
* being used by the user.
*
* @param out Pointer to store the loaded configuration
* @param[out] out Pointer to store the loaded configuration
* @param repo A repository object
* @return 0, or an error code
*/
GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo);
GIT_EXTERN(int) git_repository_config(
git_config **out,
git_repository *repo);
/**
* Get a snapshot of the repository's configuration
@@ -640,11 +646,13 @@ GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo);
* The configuration file must be freed once it's no longer
* being used by the user.
*
* @param out Pointer to store the loaded configuration
* @param[out] out Pointer to store the loaded configuration
* @param repo the repository
* @return 0, or an error code
*/
GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository *repo);
GIT_EXTERN(int) git_repository_config_snapshot(
git_config **out,
git_repository *repo);
/**
* Get the Object Database for this repository.

2
include/git2/revert.h
View File

@@ -61,7 +61,7 @@ GIT_EXTERN(int) git_revert_options_init(
*
* The returned index must be freed explicitly with `git_index_free`.
*
* @param out pointer to store the index result in
* @param[out] out pointer to store the index result in
* @param repo the repository that contains the given commits
* @param revert_commit the commit to revert
* @param our_commit the commit to revert against (eg, HEAD)

6
include/git2/revparse.h
View File

@@ -29,13 +29,15 @@ GIT_BEGIN_DECL
* The returned object should be released with `git_object_free` when no
* longer needed.
*
* @param out pointer to output object
* @param[out] out pointer to output object
* @param repo the repository to search in
* @param spec the textual specification for an object
* @return 0 on success, GIT_ENOTFOUND, GIT_EAMBIGUOUS, GIT_EINVALIDSPEC or an error code
*/
GIT_EXTERN(int) git_revparse_single(
git_object **out, git_repository *repo, const char *spec);
git_object **out,
git_repository *repo,
const char *spec);
/**
* Find a single object and intermediate reference by a revision string.

6
include/git2/revwalk.h
View File

@@ -67,7 +67,7 @@ typedef enum {
* it is possible to have several revision walkers in
* several different threads walking the same repository.
*
* @param out pointer to the new revision walker
* @param[out] out pointer to the new revision walker
* @param repo the repo to walk through
* @return 0 or an error code
*/
@@ -232,9 +232,9 @@ GIT_EXTERN(int) git_revwalk_sorting(git_revwalk *walk, unsigned int sort_mode);
/**
* Set a git_pathspec object to filter commits on
*
*
* Changing the pathspec rests the walker
*
*
* @param walk the walker being used for the traversal.
* @param pathspec Paths to filter commits on
* @return 0 or an error code

32
include/git2/signature.h
View File

@@ -31,26 +31,34 @@ GIT_BEGIN_DECL
* Note: angle brackets ('<' and '>') characters are not allowed
* to be used in either the `name` or the `email` parameter.
*
* @param out new signature, in case of error NULL
* @param[out] out new signature, in case of error NULL
* @param name name of the person
* @param email email of the person
* @param time time (in seconds from epoch) when the action happened
* @param offset timezone offset (in minutes) for the time
* @return 0 or an error code
*/
GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const char *email, git_time_t time, int offset);
GIT_EXTERN(int) git_signature_new(
git_signature **out,
const char *name,
const char *email,
git_time_t time,
int offset);
/**
* Create a new action signature with a timestamp of 'now'.
*
* Call `git_signature_free()` to free the data.
*
* @param out new signature, in case of error NULL
* @param[out] out new signature, in case of error NULL
* @param name name of the person
* @param email email of the person
* @return 0 or an error code
*/
GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const char *email);
GIT_EXTERN(int) git_signature_now(
git_signature **out,
const char *name,
const char *email);
/**
* Create a new author and/or committer signatures with default
@@ -78,8 +86,8 @@ GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const c
* `user.email` are not set and there is no fallback from an environment
* variable. One of `author_out` or `committer_out` must be set.
*
* @param author_out pointer to set the author signature, or NULL
* @param committer_out pointer to set the committer signature, or NULL
* @param[out] author_out pointer to set the author signature, or NULL
* @param[out] committer_out pointer to set the committer signature, or NULL
* @param repo repository pointer
* @return 0 on success, GIT_ENOTFOUND if config is missing, or error code
*/
@@ -100,11 +108,13 @@ GIT_EXTERN(int) git_signature_default_from_env(
* configuration files. Use `git_signature_default_from_env` to
* consider the environment variables.
*
* @param out new signature
* @param[out] out new signature
* @param repo repository pointer
* @return 0 on success, GIT_ENOTFOUND if config is missing, or error code
*/
GIT_EXTERN(int) git_signature_default(git_signature **out, git_repository *repo);
GIT_EXTERN(int) git_signature_default(
git_signature **out,
git_repository *repo);
/**
* Create a new signature by parsing the given buffer, which is
@@ -113,11 +123,13 @@ GIT_EXTERN(int) git_signature_default(git_signature **out, git_repository *repo)
* `tzoffset` is the timezone offset in `hhmm` format (note the lack
* of a colon separator).
*
* @param out new signature
* @param[out] out new signature
* @param buf signature string
* @return 0 on success, GIT_EINVALID if the signature is not parseable, or an error code
*/
GIT_EXTERN(int) git_signature_from_buffer(git_signature **out, const char *buf);
GIT_EXTERN(int) git_signature_from_buffer(
git_signature **out,
const char *buf);
/**
* Create a copy of an existing signature. All internal strings are also

2
include/git2/status.h
View File

@@ -386,7 +386,7 @@ GIT_EXTERN(int) git_status_file(
* not be accurate. To do rename detection properly, this must be called
* with no `pathspec` so that all files can be considered.
*
* @param out Pointer to store the status results in
* @param[out] out Pointer to store the status results in
* @param repo Repository object
* @param opts Status options structure
* @return 0 on success or error code

10
include/git2/submodule.h
View File

@@ -220,7 +220,7 @@ GIT_EXTERN(int) git_submodule_update(git_submodule *submodule, int init, git_sub
*
* You must call `git_submodule_free` when done with the submodule.
*
* @param out Output ptr to submodule; pass NULL to just get return code
* @param[out] out Output ptr to submodule; pass NULL to just get return code
* @param repo The parent repository
* @param name The name of or path to the submodule; trailing slashes okay
* @return 0 on success, GIT_ENOTFOUND if submodule does not exist,
@@ -236,7 +236,7 @@ GIT_EXTERN(int) git_submodule_lookup(
* Create an in-memory copy of a submodule. The copy must be explicitly
* free'd or it will leak.
*
* @param out Pointer to store the copy of the submodule.
* @param[out] out Pointer to store the copy of the submodule.
* @param source Original submodule to copy.
* @return 0
*/
@@ -289,7 +289,7 @@ GIT_EXTERN(int) git_submodule_foreach(
*
* You must call `git_submodule_free` on the submodule object when done.
*
* @param out The newly created submodule ready to open for clone
* @param[out] out The newly created submodule ready to open for clone
* @param repo The repository in which you want to create the submodule
* @param url URL for the submodule's remote
* @param path Path at which the submodule should be created
@@ -310,7 +310,7 @@ GIT_EXTERN(int) git_submodule_add_setup(
*
* This performs the necessary `git_clone` to setup a newly-created submodule.
*
* @param out The newly created repository object. Optional.
* @param[out] out The newly created repository object. Optional.
* @param submodule The submodule currently waiting for its clone.
* @param opts The options to use.
*
@@ -583,7 +583,7 @@ GIT_EXTERN(int) git_submodule_init(git_submodule *submodule, int overwrite);
* repository from a submodule in preparation to clone it from
* its remote.
*
* @param out Output pointer to the created git repository.
* @param[out] out Output pointer to the created git repository.
* @param sm The submodule to create a new subrepository from.
* @param use_gitlink Should the workdir contain a gitlink to
* the repo in .git/modules vs. repo directly in workdir.

4
include/git2/sys/commit_graph.h
View File

@@ -156,9 +156,9 @@ GIT_EXTERN(int) git_commit_graph_writer_options_init(
/**
* Create a new writer for `commit-graph` files.
*
* @param out Location to store the writer pointer.
* @param[out] out Location to store the writer pointer.
* @param objects_info_dir The `objects/info` directory.
* The `commit-graph` file will be written in this directory.
* The `commit-graph` file will be written in this directory.
* @param options The options for the commit graph writer.
* @return 0 or an error code
*/

4
include/git2/sys/config.h
View File

@@ -172,7 +172,7 @@ typedef struct {
* Create an in-memory configuration backend from a string in standard
* git configuration file format.
*
* @param out the new backend
* @param[out] out the new backend
* @param cfg the configuration that is to be parsed
* @param len the length of the string pointed to by `cfg`
* @param opts the options to initialize this backend with, or NULL
@@ -188,7 +188,7 @@ extern int git_config_backend_from_string(
* Create an in-memory configuration backend from a list of name/value
* pairs.
*
* @param out the new backend
* @param[out] out the new backend
* @param values the configuration values to set (in "key=value" format)
* @param len the length of the values array
* @param opts the options to initialize this backend with, or NULL

4
include/git2/sys/filter.h
View File

@@ -57,7 +57,7 @@ GIT_EXTERN(git_filter *) git_filter_lookup(const char *name);
* `git_filter_lookup` and `git_filter_list_push` functions to assemble
* your own chains of filters.
*
* @param out the filter list
* @param[out] out the filter list
* @param repo the repository to use for configuration
* @param mode the filter mode (direction)
* @param options the options
@@ -259,7 +259,7 @@ typedef int GIT_CALLBACK(git_filter_apply_fn)(
* with that data, the `git_writestream` will then perform the filter
* translation and stream the filtered data out to the `next` location.
*
* @param out the write stream
* @param[out] out the write stream
* @param self the filter
* @param payload a data for future filter functions
* @param src the filter source

4
include/git2/sys/hashsig.h
View File

@@ -61,7 +61,7 @@ typedef enum {
* whitespace will be removed from the buffer while it is being processed,
* modifying the buffer in place. Sorry about that!
*
* @param out The computed similarity signature.
* @param[out] out The computed similarity signature.
* @param buf The input buffer.
* @param buflen The input buffer size.
* @param opts The signature computation options (see above).
@@ -81,7 +81,7 @@ GIT_EXTERN(int) git_hashsig_create(
* This walks through the file, only loading a maximum of 4K of file data at
* a time. Otherwise, it acts just like `git_hashsig_create`.
*
* @param out The computed similarity signature.
* @param[out] out The computed similarity signature.
* @param path The path to the input file.
* @param opts The signature computation options (see above).
* @return 0 on success, GIT_EBUFS if the buffer doesn't contain enough data to

8
include/git2/sys/index.h
View File

@@ -101,12 +101,16 @@ GIT_EXTERN(size_t) git_index_reuc_entrycount(git_index *index);
* Finds the resolve undo entry that points to the given path in the Git
* index.
*
* @param at_pos the address to which the position of the reuc entry is written (optional)
* @param[out] at_pos the address to which the position of the
* reuc entry is written (optional)
* @param index an existing index object
* @param path path to search
* @return 0 if found, < 0 otherwise (GIT_ENOTFOUND)
*/
GIT_EXTERN(int) git_index_reuc_find(size_t *at_pos, git_index *index, const char *path);
GIT_EXTERN(int) git_index_reuc_find(
size_t *at_pos,
git_index *index,
const char *path);
/**
* Get a resolve undo entry from the index.

8
include/git2/sys/mempack.h
View File

@@ -39,7 +39,7 @@ GIT_BEGIN_DECL
* 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
* @param[out] 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);
@@ -105,11 +105,13 @@ GIT_EXTERN(int) git_mempack_reset(git_odb_backend *backend);
/**
* Get the total number of objects in mempack
*
* @param count The count of objects in the mempack
* @param[out] count The count of objects in the mempack
* @param backend The mempack backend
* @return 0 on success, or -1 on error
*/
GIT_EXTERN(int) git_mempack_object_count(size_t *count, git_odb_backend *backend);
GIT_EXTERN(int) git_mempack_object_count(
size_t *count,
git_odb_backend *backend);
/** @} */
GIT_END_DECL

2
include/git2/sys/midx.h
View File

@@ -60,7 +60,7 @@ GIT_EXTERN(int) git_midx_writer_options_init(
/**
* Create a new writer for `multi-pack-index` files.
*
* @param out location to store the writer pointer.
* @param[out] out location to store the writer pointer.
* @param pack_dir the directory where the `.pack` and `.idx` files are. The
* `multi-pack-index` file will be written in this directory, too.
* @return 0 or an error code

4
include/git2/sys/refdb_backend.h
View File

@@ -375,7 +375,7 @@ GIT_EXTERN(int) git_refdb_init_backend(
* opened / created, but you can use this to explicitly construct a
* filesystem refdb backend for a repository.
*
* @param backend_out Output pointer to the git_refdb_backend object
* @param[out] backend_out Output pointer to the git_refdb_backend object
* @param repo Git repository to access
* @return 0 on success, <0 error code on failure
*/
@@ -390,7 +390,7 @@ GIT_EXTERN(int) git_refdb_backend_fs(
* opened / created that uses the reftable format, but you can use this to
* explicitly construct a reftable refdb backend for a repository.
*
* @param backend_out Output pointer to the git_refdb_backend object
* @param[out] backend_out Output pointer to the git_refdb_backend object
* @param repo Git repository to access
* @return 0 on success, <0 error code on failure
*/

42
include/git2/sys/transport.h
View File

@@ -175,12 +175,15 @@ GIT_EXTERN(int) git_transport_init(
* is scanned to find a transport that implements the scheme of the URI (i.e.
* git:// or http://) and a transport object is returned to the caller.
*
* @param out The newly created transport (out)
* @param[out] out The newly created transport (out)
* @param owner The git_remote which will own this transport
* @param url The URL to connect to
* @return 0 or an error code
*/
GIT_EXTERN(int) git_transport_new(git_transport **out, git_remote *owner, const char *url);
GIT_EXTERN(int) git_transport_new(
git_transport **out,
git_remote *owner,
const char *url);
/**
* Create an ssh transport with custom git command paths
@@ -191,12 +194,15 @@ GIT_EXTERN(int) git_transport_new(git_transport **out, git_remote *owner, const
* The payload argument must be a strarray pointer with the paths for
* the `git-upload-pack` and `git-receive-pack` at index 0 and 1.
*
* @param out the resulting transport
* @param[out] out the resulting transport
* @param owner the owning remote
* @param payload a strarray with the paths
* @return 0 or an error code
*/
GIT_EXTERN(int) git_transport_ssh_with_paths(git_transport **out, git_remote *owner, void *payload);
GIT_EXTERN(int) git_transport_ssh_with_paths(
git_transport **out,
git_remote *owner,
void *payload);
/**
* Add a custom transport definition, to be used in addition to the built-in
@@ -236,7 +242,7 @@ GIT_EXTERN(int) git_transport_unregister(
/**
* Create an instance of the dummy transport.
*
* @param out The newly created transport (out)
* @param[out] out The newly created transport (out)
* @param owner The git_remote which will own this transport
* @param payload You must pass NULL for this parameter.
* @return 0 or an error code
@@ -249,7 +255,7 @@ GIT_EXTERN(int) git_transport_dummy(
/**
* Create an instance of the local transport.
*
* @param out The newly created transport (out)
* @param[out] out The newly created transport (out)
* @param owner The git_remote which will own this transport
* @param payload You must pass NULL for this parameter.
* @return 0 or an error code
@@ -262,7 +268,7 @@ GIT_EXTERN(int) git_transport_local(
/**
* Create an instance of the smart transport.
*
* @param out The newly created transport (out)
* @param[out] out The newly created transport (out)
* @param owner The git_remote which will own this transport
* @param payload A pointer to a git_smart_subtransport_definition
* @return 0 or an error code
@@ -284,12 +290,16 @@ GIT_EXTERN(int) git_transport_smart(
* refused to validate the certificate and callers should behave as
* if no callback was set), or < 0 for an error
*/
GIT_EXTERN(int) git_transport_smart_certificate_check(git_transport *transport, git_cert *cert, int valid, const char *hostname);
GIT_EXTERN(int) git_transport_smart_certificate_check(
git_transport *transport,
git_cert *cert,
int valid,
const char *hostname);
/**
* Call the credentials callback for this transport
*
* @param out the pointer where the creds are to be stored
* @param[out] out the pointer where the creds are to be stored
* @param transport a smart transport
* @param user the user we saw on the url (if any)
* @param methods available methods for authentication
@@ -298,7 +308,11 @@ GIT_EXTERN(int) git_transport_smart_certificate_check(git_transport *transport,
* refused to provide credentials and callers should behave as if no
* callback was set), or < 0 for an error
*/
GIT_EXTERN(int) git_transport_smart_credentials(git_credential **out, git_transport *transport, const char *user, int methods);
GIT_EXTERN(int) git_transport_smart_credentials(
git_credential **out,
git_transport *transport,
const char *user,
int methods);
/**
* Get a copy of the remote connect options
@@ -399,7 +413,7 @@ struct git_smart_subtransport {
/**
* A function that creates a new subtransport for the smart transport
*
* @param out the smart subtransport
* @param[out] out the smart subtransport
* @param owner the transport owner
* @param param the input parameter
* @return 0 on success, or an error code
@@ -444,7 +458,7 @@ typedef struct git_smart_subtransport_definition {
*
* This subtransport also supports https.
*
* @param out The newly created subtransport
* @param[out] out The newly created subtransport
* @param owner The smart transport to own this subtransport
* @param param custom parameters for the subtransport
* @return 0 or an error code
@@ -457,7 +471,7 @@ GIT_EXTERN(int) git_smart_subtransport_http(
/**
* Create an instance of the git subtransport.
*
* @param out The newly created subtransport
* @param[out] out The newly created subtransport
* @param owner The smart transport to own this subtransport
* @param param custom parameters for the subtransport
* @return 0 or an error code
@@ -470,7 +484,7 @@ GIT_EXTERN(int) git_smart_subtransport_git(
/**
* Create an instance of the ssh subtransport.
*
* @param out The newly created subtransport
* @param[out] out The newly created subtransport
* @param owner The smart transport to own this subtransport
* @param param custom parameters for the subtransport
* @return 0 or an error code

6
include/git2/tag.h
View File

@@ -25,7 +25,7 @@ GIT_BEGIN_DECL
/**
* Lookup a tag object from the repository.
*
* @param out pointer to the looked up tag
* @param[out] out pointer to the looked up tag
* @param repo the repo to use when locating the tag.
* @param id identity of the tag to locate.
* @return 0 or an error code
@@ -39,7 +39,7 @@ GIT_EXTERN(int) git_tag_lookup(
*
* @see git_object_lookup_prefix
*
* @param out pointer to the looked up tag
* @param[out] out pointer to the looked up tag
* @param repo the repo to use when locating the tag.
* @param id identity of the tag to locate.
* @param len the length of the short identifier
@@ -361,7 +361,7 @@ GIT_EXTERN(int) git_tag_peel(
* Create an in-memory copy of a tag. The copy must be explicitly
* free'd or it will leak.
*
* @param out Pointer to store the copy of the tag
* @param[out] out Pointer to store the copy of the tag
* @param source Original tag to copy
* @return 0
*/

6
include/git2/transaction.h
View File

@@ -25,11 +25,13 @@ GIT_BEGIN_DECL
* This does not lock anything, but sets up the transaction object to
* know from which repository to lock.
*
* @param out the resulting transaction
* @param[out] out the resulting transaction
* @param repo the repository in which to lock
* @return 0 or an error code
*/
GIT_EXTERN(int) git_transaction_new(git_transaction **out, git_repository *repo);
GIT_EXTERN(int) git_transaction_new(
git_transaction **out,
git_repository *repo);
/**
* Lock a reference

7
include/git2/transport.h
View File

@@ -37,12 +37,15 @@ typedef int GIT_CALLBACK(git_transport_message_cb)(const char *str, int len, voi
/**
* Signature of a function which creates a transport.
*
* @param out the transport generate
* @param[out] out the transport generate
* @param owner the owner for the transport
* @param param the param to the transport creation
* @return 0 on success or an error code
*/
typedef int GIT_CALLBACK(git_transport_cb)(git_transport **out, git_remote *owner, void *param);
typedef int GIT_CALLBACK(git_transport_cb)(
git_transport **out,
git_remote *owner,
void *param);
/** @} */
GIT_END_DECL

10
include/git2/tree.h
View File

@@ -38,7 +38,7 @@ GIT_EXTERN(int) git_tree_lookup(
*
* @see git_object_lookup_prefix
*
* @param out pointer to the looked up tree
* @param[out] out pointer to the looked up tree
* @param repo the repo to use when locating the tree.
* @param id identity of the tree to locate.
* @param len the length of the short identifier
@@ -134,7 +134,7 @@ GIT_EXTERN(const git_tree_entry *) git_tree_entry_byid(
* Unlike the other lookup functions, the returned tree entry is owned by
* the user and must be freed explicitly with `git_tree_entry_free()`.
*
* @param out Pointer where to store the tree entry
* @param[out] out Pointer where to store the tree entry
* @param root Previously loaded tree which is the root of the relative path
* @param path Path to the contained entry
* @return 0 on success; GIT_ENOTFOUND if the path does not exist
@@ -246,7 +246,7 @@ GIT_EXTERN(int) git_tree_entry_to_object(
* If the `source` parameter is NULL, the tree builder will start with no
* entries and will have to be filled manually.
*
* @param out Pointer where to store the tree builder
* @param[out] out Pointer where to store the tree builder
* @param repo Repository in which to store the object
* @param source Source tree to initialize the builder (optional)
* @return 0 on success; error code otherwise
@@ -313,7 +313,7 @@ GIT_EXTERN(const git_tree_entry *) git_treebuilder_get(
* correct type. If you do not want this behavior, set the
* `GIT_OPT_ENABLE_STRICT_OBJECT_CREATION` library option to false.
*
* @param out Pointer to store the entry (optional)
* @param[out] out Pointer to store the entry (optional)
* @param bld Tree builder
* @param filename Filename of the entry
* @param id SHA1 oid of the entry
@@ -427,7 +427,7 @@ GIT_EXTERN(int) git_tree_walk(
* Create an in-memory copy of a tree. The copy must be explicitly
* free'd or it will leak.
*
* @param out Pointer to store the copy of the tree
* @param[out] out Pointer to store the copy of the tree
* @param source Original tree to copy
* @return 0
*/

22
include/git2/worktree.h
View File

@@ -37,12 +37,15 @@ GIT_EXTERN(int) git_worktree_list(git_strarray *out, git_repository *repo);
/**
* Lookup a working tree by its name for a given repository
*
* @param out Output pointer to looked up worktree or `NULL`
* @param[out] out Output pointer to looked up worktree or `NULL`
* @param repo The repository containing worktrees
* @param name Name of the working tree to look up
* @return 0 or an error code
*/
GIT_EXTERN(int) git_worktree_lookup(git_worktree **out, git_repository *repo, const char *name);
GIT_EXTERN(int) git_worktree_lookup(
git_worktree **out,
git_repository *repo,
const char *name);
/**
* Open a worktree of a given repository
@@ -51,11 +54,13 @@ GIT_EXTERN(int) git_worktree_lookup(git_worktree **out, git_repository *repo, co
* function will look up the worktree inside the parent
* repository and create a new `git_worktree` structure.
*
* @param out Out-pointer for the newly allocated worktree
* @param[out] out Out-pointer for the newly allocated worktree
* @param repo Repository to look up worktree for
* @return 0 or an error code
*/
GIT_EXTERN(int) git_worktree_open_from_repository(git_worktree **out, git_repository *repo);
GIT_EXTERN(int) git_worktree_open_from_repository(
git_worktree **out,
git_repository *repo);
/**
* Free a previously allocated worktree
@@ -123,15 +128,18 @@ GIT_EXTERN(int) git_worktree_add_options_init(git_worktree_add_options *opts,
* required data structures inside the repository and check out
* the current HEAD at `path`
*
* @param out Output pointer containing new working tree
* @param[out] out Output pointer containing new working tree
* @param repo Repository to create working tree for
* @param name Name of the working tree
* @param path Path to create working tree at
* @param opts Options to modify default behavior. May be NULL
* @return 0 or an error code
*/
GIT_EXTERN(int) git_worktree_add(git_worktree **out, git_repository *repo,
const char *name, const char *path,
GIT_EXTERN(int) git_worktree_add(
git_worktree **out,
git_repository *repo,
const char *name,
const char *path,
const git_worktree_add_options *opts);
/**