diff --git a/include/git2/annotated_commit.h b/include/git2/annotated_commit.h index 3b7103f20..04f3b1c38 100644 --- a/include/git2/annotated_commit.h +++ b/include/git2/annotated_commit.h @@ -13,9 +13,16 @@ /** * @file git2/annotated_commit.h - * @brief Git annotated commit routines + * @brief A commit and information about how it was looked up by the user. * @defgroup git_annotated_commit Git annotated commit routines * @ingroup Git + * + * An "annotated commit" is a commit that contains information about + * how the commit was resolved, which can be used for maintaining the + * user's "intent" through commands like merge and rebase. For example, + * if a user wants to "merge HEAD" then an annotated commit is used to + * both contain the HEAD commit _and_ the fact that it was resolved as + * the HEAD ref. * @{ */ GIT_BEGIN_DECL @@ -25,7 +32,7 @@ GIT_BEGIN_DECL * The resulting git_annotated_commit must be freed with * `git_annotated_commit_free`. * - * @param out pointer to store the git_annotated_commit result in + * @param[out] out pointer to store the git_annotated_commit result in * @param repo repository that contains the given reference * @param ref reference to use to lookup the git_annotated_commit * @return 0 on success or error code @@ -40,7 +47,7 @@ GIT_EXTERN(int) git_annotated_commit_from_ref( * The resulting git_annotated_commit must be freed with * `git_annotated_commit_free`. * - * @param out pointer to store the git_annotated_commit result in + * @param[out] out pointer to store the git_annotated_commit result in * @param repo repository that contains the given commit * @param branch_name name of the (remote) branch * @param remote_url url of the remote @@ -67,7 +74,7 @@ GIT_EXTERN(int) git_annotated_commit_from_fetchhead( * most specific function (eg `git_annotated_commit_from_ref`) * instead of this one when that data is known. * - * @param out pointer to store the git_annotated_commit result in + * @param[out] out pointer to store the git_annotated_commit result in * @param repo repository that contains the given commit * @param id the commit object id to lookup * @return 0 on success or error code @@ -84,7 +91,7 @@ GIT_EXTERN(int) git_annotated_commit_lookup( * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for * information on the syntax accepted. * - * @param out pointer to store the git_annotated_commit result in + * @param[out] out pointer to store the git_annotated_commit result in * @param repo repository that contains the given commit * @param revspec the extended sha syntax string to use to lookup the commit * @return 0 on success or error code diff --git a/include/git2/apply.h b/include/git2/apply.h index db652bde0..7ab939d1f 100644 --- a/include/git2/apply.h +++ b/include/git2/apply.h @@ -14,9 +14,12 @@ /** * @file git2/apply.h - * @brief Git patch application routines + * @brief Apply patches to the working directory or index * @defgroup git_apply Git patch application routines * @ingroup Git + * + * Mechanisms to apply a patch to the index, the working directory, + * or both. * @{ */ GIT_BEGIN_DECL @@ -57,7 +60,15 @@ typedef int GIT_CALLBACK(git_apply_hunk_cb)( const git_diff_hunk *hunk, void *payload); -/** Flags controlling the behavior of git_apply */ +/** + * Flags controlling the behavior of `git_apply`. + * + * When the callback: + * - returns < 0, the apply process will be aborted. + * - returns > 0, the hunk will not be applied, but the apply process + * continues + * - returns 0, the hunk is applied, and the apply process continues. + */ typedef enum { /** * Don't actually make changes, just test that the patch applies. @@ -67,12 +78,19 @@ typedef enum { } git_apply_flags_t; /** - * Apply options structure + * Apply options structure. + * + * When the callback: + * - returns < 0, the apply process will be aborted. + * - returns > 0, the hunk will not be applied, but the apply process + * continues + * - returns 0, the hunk is applied, and the apply process continues. * * Initialize with `GIT_APPLY_OPTIONS_INIT`. Alternatively, you can * use `git_apply_options_init`. * - * @see git_apply_to_tree, git_apply + * @see git_apply_to_tree + * @see git_apply */ typedef struct { unsigned int version; /**< The version */ @@ -83,14 +101,17 @@ typedef struct { /** When applying a patch, callback that will be made per hunk. */ git_apply_hunk_cb hunk_cb; - /** Payload passed to both delta_cb & hunk_cb. */ + /** Payload passed to both `delta_cb` & `hunk_cb`. */ void *payload; - /** Bitmask of git_apply_flags_t */ + /** Bitmask of `git_apply_flags_t` */ unsigned int flags; } git_apply_options; +/** Current version for the `git_apply_options` structure */ #define GIT_APPLY_OPTIONS_VERSION 1 + +/** Static constructor for `git_apply_options` */ #define GIT_APPLY_OPTIONS_INIT {GIT_APPLY_OPTIONS_VERSION} /** diff --git a/include/git2/attr.h b/include/git2/attr.h index 69929b3df..e5216fef9 100644 --- a/include/git2/attr.h +++ b/include/git2/attr.h @@ -12,9 +12,13 @@ /** * @file git2/attr.h - * @brief Git attribute management routines + * @brief Attribute management routines * @defgroup git_attr Git attribute management routines * @ingroup Git + * + * Attributes specify additional information about how git should + * handle particular paths - for example, they may indicate whether + * a particular filter is applied, like LFS or line ending conversions. * @{ */ GIT_BEGIN_DECL @@ -114,8 +118,12 @@ GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr); * use index only for creating archives or for a bare repo (if an * index has been specified for the bare repo). */ + +/** Examine attribute in working directory, then index */ #define GIT_ATTR_CHECK_FILE_THEN_INDEX 0 +/** Examine attribute in index, then working directory */ #define GIT_ATTR_CHECK_INDEX_THEN_FILE 1 +/** Examine attributes only in the index */ #define GIT_ATTR_CHECK_INDEX_ONLY 2 /** @@ -132,8 +140,12 @@ GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr); * Passing the `GIT_ATTR_CHECK_INCLUDE_COMMIT` flag will use attributes * from a `.gitattributes` file in a specific commit. */ + +/** Ignore system attributes */ #define GIT_ATTR_CHECK_NO_SYSTEM (1 << 2) +/** Honor `.gitattributes` in the HEAD revision */ #define GIT_ATTR_CHECK_INCLUDE_HEAD (1 << 3) +/** Honor `.gitattributes` in a specific commit */ #define GIT_ATTR_CHECK_INCLUDE_COMMIT (1 << 4) /** @@ -158,7 +170,10 @@ typedef struct { git_oid attr_commit_id; } git_attr_options; +/** Current version for the `git_attr_options` structure */ #define GIT_ATTR_OPTIONS_VERSION 1 + +/** Static constructor for `git_attr_options` */ #define GIT_ATTR_OPTIONS_INIT {GIT_ATTR_OPTIONS_VERSION} /** diff --git a/include/git2/blame.h b/include/git2/blame.h index 2ddd9e077..f3e66924c 100644 --- a/include/git2/blame.h +++ b/include/git2/blame.h @@ -13,9 +13,14 @@ /** * @file git2/blame.h - * @brief Git blame routines + * @brief Specify a file's most recent changes per-line * @defgroup git_blame Git blame routines * @ingroup Git + * + * Producing a "blame" (or "annotated history") decorates individual + * lines in a file with the commit that introduced that particular line + * of changes. This can be useful to indicate when and why a particular + * change was made. * @{ */ GIT_BEGIN_DECL @@ -122,7 +127,10 @@ typedef struct git_blame_options { size_t max_line; } git_blame_options; +/** Current version for the `git_blame_options` structure */ #define GIT_BLAME_OPTIONS_VERSION 1 + +/** Static constructor for `git_blame_options` */ #define GIT_BLAME_OPTIONS_INIT {GIT_BLAME_OPTIONS_VERSION} /** diff --git a/include/git2/blob.h b/include/git2/blob.h index e8f838132..0ed168555 100644 --- a/include/git2/blob.h +++ b/include/git2/blob.h @@ -15,9 +15,13 @@ /** * @file git2/blob.h - * @brief Git blob load and write routines + * @brief A blob represents a file in a git repository. * @defgroup git_blob Git blob load and write routines * @ingroup Git + * + * A blob represents a file in a git repository. This is the raw data + * as it is stored in the repository itself. Blobs may be "filtered" + * to produce the on-disk content. * @{ */ GIT_BEGIN_DECL @@ -25,12 +29,15 @@ GIT_BEGIN_DECL /** * Lookup a blob object from a repository. * - * @param blob pointer to the looked up blob + * @param[out] blob pointer to the looked up blob * @param repo the repo to use when locating the blob. * @param id identity of the blob to locate. * @return 0 or an error code */ -GIT_EXTERN(int) git_blob_lookup(git_blob **blob, git_repository *repo, const git_oid *id); +GIT_EXTERN(int) git_blob_lookup( + git_blob **blob, + git_repository *repo, + const git_oid *id); /** * Lookup a blob object from a repository, @@ -38,7 +45,7 @@ GIT_EXTERN(int) git_blob_lookup(git_blob **blob, git_repository *repo, const git * * @see git_object_lookup_prefix * - * @param blob pointer to the looked up blob + * @param[out] blob pointer to the looked up blob * @param repo the repo to use when locating the blob. * @param id identity of the blob to locate. * @param len the length of the short identifier @@ -84,7 +91,7 @@ GIT_EXTERN(git_repository *) git_blob_owner(const git_blob *blob); * time. * * @param blob pointer to the blob - * @return the pointer, or NULL on error + * @return @type `unsigned char *` the pointer, or NULL on error */ GIT_EXTERN(const void *) git_blob_rawcontent(const git_blob *blob); @@ -98,6 +105,8 @@ GIT_EXTERN(git_object_size_t) git_blob_rawsize(const git_blob *blob); /** * Flags to control the functionality of `git_blob_filter`. + * + * @flags */ typedef enum { /** When set, filters will not be applied to binary files. */ @@ -128,16 +137,34 @@ typedef enum { * Initialize with `GIT_BLOB_FILTER_OPTIONS_INIT`. Alternatively, you can * use `git_blob_filter_options_init`. * + * @options[version] GIT_BLOB_FILTER_OPTIONS_VERSION + * @options[init_macro] GIT_BLOB_FILTER_OPTIONS_INIT + * @options[init_function] git_blob_filter_options_init */ typedef struct { + /** Version number of the options structure. */ int version; - /** Flags to control the filtering process, see `git_blob_filter_flag_t` above */ + /** + * Flags to control the filtering process, see `git_blob_filter_flag_t` above. + * + * @type[flags] git_blob_filter_flag_t + */ uint32_t flags; #ifdef GIT_DEPRECATE_HARD + /** + * Unused and reserved for ABI compatibility. + * + * @deprecated this value should not be set + */ void *reserved; #else + /** + * This value is unused and reserved for API compatibility. + * + * @deprecated this value should not be set + */ git_oid *commit_id; #endif @@ -148,8 +175,18 @@ typedef struct { git_oid attr_commit_id; } git_blob_filter_options; +/** + * The current version number for the `git_blob_filter_options` structure ABI. + */ #define GIT_BLOB_FILTER_OPTIONS_VERSION 1 -#define GIT_BLOB_FILTER_OPTIONS_INIT {GIT_BLOB_FILTER_OPTIONS_VERSION, GIT_BLOB_FILTER_CHECK_FOR_BINARY} + +/** + * The default values for `git_blob_filter_options`. + */ +#define GIT_BLOB_FILTER_OPTIONS_INIT { \ + GIT_BLOB_FILTER_OPTIONS_VERSION, \ + GIT_BLOB_FILTER_CHECK_FOR_BINARY \ + } /** * Initialize git_blob_filter_options structure @@ -158,10 +195,12 @@ typedef struct { * to creating an instance with `GIT_BLOB_FILTER_OPTIONS_INIT`. * * @param opts The `git_blob_filter_options` struct to initialize. - * @param version The struct version; pass `GIT_BLOB_FILTER_OPTIONS_VERSION`. + * @param version The struct version; pass GIT_BLOB_FILTER_OPTIONS_VERSION * @return Zero on success; -1 on failure. */ -GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsigned int version); +GIT_EXTERN(int) git_blob_filter_options_init( + git_blob_filter_options *opts, + unsigned int version); /** * Get a buffer with the filtered content of a blob. @@ -171,7 +210,7 @@ GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsi * CRLF filtering or other types of changes depending on the file * attributes set for the blob and the content detected in it. * - * The output is written into a `git_buf` which the caller must free + * The output is written into a `git_buf` which the caller must dispose * when done (via `git_buf_dispose`). * * If no filters need to be applied, then the `out` buffer will just @@ -183,7 +222,7 @@ GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsi * @param blob Pointer to the blob * @param as_path Path used for file attribute lookups, etc. * @param opts Options to use for filtering the blob - * @return 0 on success or an error code + * @return @type[enum] git_error_code 0 on success or an error code */ GIT_EXTERN(int) git_blob_filter( git_buf *out, @@ -192,10 +231,10 @@ GIT_EXTERN(int) git_blob_filter( git_blob_filter_options *opts); /** - * Read a file from the working folder of a repository - * and write it to the Object Database as a loose blob + * Read a file from the working folder of a repository and write it + * to the object database. * - * @param id return the id of the written blob + * @param[out] id return the id of the written blob * @param repo repository where the blob will be written. * this repository cannot be bare * @param relative_path file from which the blob will be created, @@ -205,19 +244,23 @@ GIT_EXTERN(int) git_blob_filter( GIT_EXTERN(int) git_blob_create_from_workdir(git_oid *id, git_repository *repo, const char *relative_path); /** - * Read a file from the filesystem and write its content - * to the Object Database as a loose blob + * Read a file from the filesystem (not necessarily inside the + * working folder of the repository) and write it to the object + * database. * - * @param id return the id of the written blob + * @param[out] id return the id of the written blob * @param repo repository where the blob will be written. * this repository can be bare or not * @param path file from which the blob will be created * @return 0 or an error code */ -GIT_EXTERN(int) git_blob_create_from_disk(git_oid *id, git_repository *repo, const char *path); +GIT_EXTERN(int) git_blob_create_from_disk( + git_oid *id, + git_repository *repo, + const char *path); /** - * Create a stream to write a new blob into the object db + * Create a stream to write a new blob into the object database. * * This function may need to buffer the data on disk and will in * general not be the right choice if you know the size of the data @@ -234,7 +277,7 @@ GIT_EXTERN(int) git_blob_create_from_disk(git_oid *id, git_repository *repo, con * what git filters should be applied to the object before it is written * to the object database. * - * @param out the stream into which to write + * @param[out] out the stream into which to write * @param repo Repository where the blob will be written. * This repository can be bare or not. * @param hintpath If not NULL, will be used to select data filters @@ -247,11 +290,11 @@ GIT_EXTERN(int) git_blob_create_from_stream( const char *hintpath); /** - * Close the stream and write the blob to the object db + * Close the stream and finalize writing the blob to the object database. * * The stream will be closed and freed. * - * @param out the id of the new blob + * @param[out] out the id of the new blob * @param stream the stream to close * @return 0 or an error code */ @@ -260,9 +303,9 @@ GIT_EXTERN(int) git_blob_create_from_stream_commit( git_writestream *stream); /** - * Write an in-memory buffer to the ODB as a blob + * Write an in-memory buffer to the object database as a blob. * - * @param id return the id of the written blob + * @param[out] id return the id of the written blob * @param repo repository where the blob will be written * @param buffer data to be written into the blob * @param len length of the data @@ -272,14 +315,14 @@ GIT_EXTERN(int) git_blob_create_from_buffer( git_oid *id, git_repository *repo, const void *buffer, size_t len); /** - * Determine if the blob content is most certainly binary or not. + * Determine if the blob content is most likely binary or not. * * The heuristic used to guess if a file is binary is taken from core git: * Searching for NUL bytes and looking for a reasonable ratio of printable * to non-printable characters among the first 8000 bytes. * * @param blob The blob which content should be analyzed - * @return 1 if the content of the blob is detected + * @return @type bool 1 if the content of the blob is detected * as binary; 0 otherwise. */ GIT_EXTERN(int) git_blob_is_binary(const git_blob *blob); @@ -300,7 +343,7 @@ GIT_EXTERN(int) git_blob_data_is_binary(const char *data, size_t len); * Create an in-memory copy of a blob. The copy must be explicitly * free'd or it will leak. * - * @param out Pointer to store the copy of the object + * @param[out] out Pointer to store the copy of the object * @param source Original object to copy * @return 0. */ diff --git a/include/git2/branch.h b/include/git2/branch.h index 27c6fa157..56d737d0f 100644 --- a/include/git2/branch.h +++ b/include/git2/branch.h @@ -13,9 +13,15 @@ /** * @file git2/branch.h - * @brief Git branch parsing routines + * @brief Branch creation and handling * @defgroup git_branch Git branch management * @ingroup Git + * + * A branch is a specific type of reference, at any particular time, + * a git working directory typically is said to have a branch "checked out", + * meaning that commits that are created will be made "on" a branch. + * This occurs by updating the branch reference to point to the new + * commit. The checked out branch is indicated by the `HEAD` meta-ref. * @{ */ GIT_BEGIN_DECL @@ -33,18 +39,13 @@ GIT_BEGIN_DECL * See `git_tag_create()` for rules about valid names. * * @param 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 - * an already existing branch name. - * + * validated for consistency. It should also not conflict with + * an already existing branch name. * @param target Commit to which this branch should point. This object - * must belong to the given `repo`. - * + * must belong to the given `repo`. * @param force Overwrite existing branch. - * * @return 0, GIT_EINVALIDSPEC or an error code. * A proper reference is written in the refs/heads namespace * pointing to the provided target commit. @@ -63,15 +64,21 @@ GIT_EXTERN(int) git_branch_create( * commit, which lets you specify which extended sha syntax string was * specified by a user, allowing for more exact reflog messages. * - * See the documentation for `git_branch_create()`. - * - * @see git_branch_create + * @param ref_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 + * an already existing branch name. + * @param target Annotated commit to which this branch should point. This + * object must belong to the given `repo`. + * @param force Overwrite existing branch. + * @return 0, GIT_EINVALIDSPEC or an error code. */ GIT_EXTERN(int) git_branch_create_from_annotated( git_reference **ref_out, - git_repository *repository, + git_repository *repo, const char *branch_name, - const git_annotated_commit *commit, + const git_annotated_commit *target, int force); /** @@ -222,7 +229,7 @@ GIT_EXTERN(int) git_branch_upstream( * @param branch the branch to configure * @param branch_name remote-tracking or local branch to set as upstream. * - * @return 0 on success; GIT_ENOTFOUND if there's no branch named `branch_name` + * @return @type git_error_t 0 on success; GIT_ENOTFOUND if there's no branch named `branch_name` * or an error code */ GIT_EXTERN(int) git_branch_set_upstream( diff --git a/include/git2/buffer.h b/include/git2/buffer.h index 9fa972034..3fe4f8548 100644 --- a/include/git2/buffer.h +++ b/include/git2/buffer.h @@ -11,9 +11,12 @@ /** * @file git2/buffer.h - * @brief Buffer export structure - * + * @brief A data structure to return data to callers * @ingroup Git + * + * The `git_buf` buffer is used to return arbitrary data - typically + * strings - to callers. Callers are responsible for freeing the memory + * in a buffer with the `git_buf_dispose` function. * @{ */ GIT_BEGIN_DECL @@ -67,8 +70,7 @@ typedef struct { */ GIT_EXTERN(void) git_buf_dispose(git_buf *buffer); +/** @} */ GIT_END_DECL -/** @} */ - #endif diff --git a/include/git2/cert.h b/include/git2/cert.h index 05213a571..7b91b638d 100644 --- a/include/git2/cert.h +++ b/include/git2/cert.h @@ -12,7 +12,7 @@ /** * @file git2/cert.h - * @brief Git certificate objects + * @brief TLS and SSH certificate handling * @defgroup git_cert Certificate objects * @ingroup Git * @{ @@ -169,4 +169,5 @@ typedef struct { /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/checkout.h b/include/git2/checkout.h index 3705a8d7b..bdea92845 100644 --- a/include/git2/checkout.h +++ b/include/git2/checkout.h @@ -13,9 +13,13 @@ /** * @file git2/checkout.h - * @brief Git checkout routines + * @brief Update the contents of the working directory * @defgroup git_checkout Git checkout routines * @ingroup Git + * + * Update the contents of the working directory, or a subset of the + * files in the working directory, to point to the data in the index + * or a specific commit. * @{ */ GIT_BEGIN_DECL @@ -103,6 +107,8 @@ GIT_BEGIN_DECL * files or folders that fold to the same name on case insensitive * filesystems. This can cause files to retain their existing names * and write through existing symbolic links. + * + * @flags */ typedef enum { /** @@ -212,6 +218,8 @@ typedef enum { * Notification callbacks are made prior to modifying any files on disk, * so canceling on any notification will still happen prior to any files * being modified. + * + * @flags */ typedef enum { GIT_CHECKOUT_NOTIFY_NONE = 0, @@ -253,7 +261,17 @@ typedef struct { size_t chmod_calls; } git_checkout_perfdata; -/** Checkout notification callback function */ +/** + * Checkout notification callback function. + * + * @param why the notification reason + * @param path the path to the file being checked out + * @param baseline the baseline's diff file information + * @param target the checkout target diff file information + * @param workdir the working directory diff file information + * @param payload the user-supplied callback payload + * @return 0 on success, or an error code + */ typedef int GIT_CALLBACK(git_checkout_notify_cb)( git_checkout_notify_t why, const char *path, @@ -262,14 +280,26 @@ typedef int GIT_CALLBACK(git_checkout_notify_cb)( const git_diff_file *workdir, void *payload); -/** Checkout progress notification function */ +/** + * Checkout progress notification function. + * + * @param path the path to the file being checked out + * @param completed_steps number of checkout steps completed + * @param total_steps number of total steps in the checkout process + * @param payload the user-supplied callback payload + */ typedef void GIT_CALLBACK(git_checkout_progress_cb)( const char *path, size_t completed_steps, size_t total_steps, void *payload); -/** Checkout perfdata notification function */ +/** + * Checkout performance data reporting function. + * + * @param perfdata the performance data for the checkout + * @param payload the user-supplied callback payload + */ typedef void GIT_CALLBACK(git_checkout_perfdata_cb)( const git_checkout_perfdata *perfdata, void *payload); @@ -280,10 +310,18 @@ typedef void GIT_CALLBACK(git_checkout_perfdata_cb)( * Initialize with `GIT_CHECKOUT_OPTIONS_INIT`. Alternatively, you can * use `git_checkout_options_init`. * + * @options[version] GIT_CHECKOUT_OPTIONS_VERSION + * @options[init_macro] GIT_CHECKOUT_OPTIONS_INIT + * @options[init_function] git_checkout_options_init */ typedef struct git_checkout_options { unsigned int version; /**< The version */ + /** + * Checkout strategy. Default is a safe checkout. + * + * @type[flags] git_checkout_strategy_t + */ unsigned int checkout_strategy; /**< default will be a safe checkout */ int disable_filters; /**< don't apply filters like CRLF conversion */ @@ -291,7 +329,13 @@ typedef struct git_checkout_options { unsigned int file_mode; /**< default is 0644 or 0755 as dictated by blob */ int file_open_flags; /**< default is O_CREAT | O_TRUNC | O_WRONLY */ - unsigned int notify_flags; /**< see `git_checkout_notify_t` above */ + /** + * Checkout notification flags specify what operations the notify + * callback is invoked for. + * + * @type[flags] git_checkout_notify_t + */ + unsigned int notify_flags; /** * Optional callback to get notifications on specific file states. @@ -346,8 +390,12 @@ typedef struct git_checkout_options { void *perfdata_payload; } git_checkout_options; + +/** Current version for the `git_checkout_options` structure */ #define GIT_CHECKOUT_OPTIONS_VERSION 1 -#define GIT_CHECKOUT_OPTIONS_INIT {GIT_CHECKOUT_OPTIONS_VERSION} + +/** Static constructor for `git_checkout_options` */ +#define GIT_CHECKOUT_OPTIONS_INIT { GIT_CHECKOUT_OPTIONS_VERSION } /** * Initialize git_checkout_options structure @@ -416,4 +464,5 @@ GIT_EXTERN(int) git_checkout_tree( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/cherrypick.h b/include/git2/cherrypick.h index 0e6a252e6..e6cf99ea5 100644 --- a/include/git2/cherrypick.h +++ b/include/git2/cherrypick.h @@ -13,9 +13,12 @@ /** * @file git2/cherrypick.h - * @brief Git cherry-pick routines + * @brief Cherry-pick the contents of an individual commit * @defgroup git_cherrypick Git cherry-pick routines * @ingroup Git + * + * "Cherry-pick" will attempts to re-apply the changes in an + * individual commit to the current index and working directory. * @{ */ GIT_BEGIN_DECL @@ -33,8 +36,13 @@ typedef struct { git_checkout_options checkout_opts; /**< Options for the checkout */ } git_cherrypick_options; +/** Current version for the `git_cherrypick_options` structure */ #define GIT_CHERRYPICK_OPTIONS_VERSION 1 -#define GIT_CHERRYPICK_OPTIONS_INIT {GIT_CHERRYPICK_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT} + +/** Static constructor for `git_cherrypick_options` */ +#define GIT_CHERRYPICK_OPTIONS_INIT { \ + GIT_CHERRYPICK_OPTIONS_VERSION, 0, \ + GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT } /** * Initialize git_cherrypick_options structure @@ -89,4 +97,3 @@ GIT_EXTERN(int) git_cherrypick( GIT_END_DECL #endif - diff --git a/include/git2/clone.h b/include/git2/clone.h index 0e3012eea..0d06a41df 100644 --- a/include/git2/clone.h +++ b/include/git2/clone.h @@ -17,9 +17,13 @@ /** * @file git2/clone.h - * @brief Git cloning routines + * @brief Clone a remote repository to the local disk * @defgroup git_clone Git cloning routines * @ingroup Git + * + * Clone will take a remote repository - located on a remote server + * accessible by HTTPS or SSH, or a repository located elsewhere on + * the local disk - and place a copy in the given local path. * @{ */ GIT_BEGIN_DECL @@ -59,7 +63,7 @@ typedef enum { * Callers of git_clone may provide a function matching this signature to override * the remote creation and customization process during a clone operation. * - * @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 @@ -81,7 +85,7 @@ typedef int GIT_CALLBACK(git_remote_create_cb)( * to override the repository creation and customization process * during a clone operation. * - * @param out the resulting repository + * @param[out] out the resulting repository * @param path path in which to create the repository * @param bare whether the repository is bare. This is the value from the clone options * @param payload payload specified by the options @@ -99,6 +103,9 @@ typedef int GIT_CALLBACK(git_repository_create_cb)( * Initialize with `GIT_CLONE_OPTIONS_INIT`. Alternatively, you can * use `git_clone_options_init`. * + * @options[version] GIT_CLONE_OPTIONS_VERSION + * @options[init_macro] GIT_CLONE_OPTIONS_INIT + * @options[init_function] git_clone_options_init */ typedef struct git_clone_options { unsigned int version; @@ -163,7 +170,10 @@ typedef struct git_clone_options { void *remote_cb_payload; } git_clone_options; +/** Current version for the `git_clone_options` structure */ #define GIT_CLONE_OPTIONS_VERSION 1 + +/** Static constructor for `git_clone_options` */ #define GIT_CLONE_OPTIONS_INIT \ { GIT_CLONE_OPTIONS_VERSION, \ GIT_CHECKOUT_OPTIONS_INIT, \ @@ -190,7 +200,7 @@ GIT_EXTERN(int) git_clone_options_init( * git's defaults. You can use the options in the callback to * customize how these are created. * - * @param out pointer that will receive the resulting repository object + * @param[out] out pointer that will receive the resulting repository object * @param url the remote repository to clone * @param local_path local directory to clone to * @param options configuration options for the clone. If NULL, the @@ -207,4 +217,5 @@ GIT_EXTERN(int) git_clone( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/commit.h b/include/git2/commit.h index 88c21e0c9..b998e1889 100644 --- a/include/git2/commit.h +++ b/include/git2/commit.h @@ -14,9 +14,13 @@ /** * @file git2/commit.h - * @brief Git commit parsing, formatting routines + * @brief A representation of a set of changes in the repository * @defgroup git_commit Git commit parsing, formatting routines * @ingroup Git + * + * A commit represents a set of changes made to the files within a + * repository, and metadata about who made the changes, and when the + * changes were made. * @{ */ GIT_BEGIN_DECL @@ -380,7 +384,38 @@ GIT_EXTERN(int) git_commit_create( * * All other parameters remain the same as `git_commit_create()`. * - * @see git_commit_create + * @param id Pointer in which to store the OID of the newly created commit + * + * @param repo Repository where to store the commit + * + * @param update_ref If not NULL, name of the reference that + * will be updated to point to this commit. If the reference + * is not direct, it will be resolved to a direct reference. + * Use "HEAD" to update the HEAD of the current branch and + * make it point to this commit. If the reference doesn't + * exist yet, it will be created. If it does exist, the first + * parent must be the tip of this branch. + * + * @param author Signature with author and author time of commit + * + * @param committer Signature with committer and * commit time of commit + * + * @param message_encoding The encoding for the message in the + * commit, represented with a standard encoding name. + * E.g. "UTF-8". If NULL, no encoding header is written and + * UTF-8 is assumed. + * + * @param message Full message for this commit + * + * @param tree An instance of a `git_tree` object that will + * be used as the tree for the commit. This tree object must + * also be owned by the given `repo`. + * + * @param parent_count Number of parents for this commit + * + * @return 0 or an error code + * The created commit will be written to the Object Database and + * the given reference will be updated to point to it */ GIT_EXTERN(int) git_commit_create_v( git_oid *id, @@ -416,7 +451,10 @@ typedef struct { const char *message_encoding; } git_commit_create_options; +/** Current version for the `git_commit_create_options` structure */ #define GIT_COMMIT_CREATE_OPTIONS_VERSION 1 + +/** Static constructor for `git_commit_create_options` */ #define GIT_COMMIT_CREATE_OPTIONS_INIT { GIT_COMMIT_CREATE_OPTIONS_VERSION } /** @@ -456,7 +494,36 @@ GIT_EXTERN(int) git_commit_create_from_stage( * * All parameters have the same meanings as in `git_commit_create()`. * - * @see git_commit_create + * @param id Pointer in which to store the OID of the newly created commit + * + * @param commit_to_amend The commit to amend + * + * @param update_ref If not NULL, name of the reference that + * will be updated to point to this commit. If the reference + * is not direct, it will be resolved to a direct reference. + * Use "HEAD" to update the HEAD of the current branch and + * make it point to this commit. If the reference doesn't + * exist yet, it will be created. If it does exist, the first + * parent must be the tip of this branch. + * + * @param author Signature with author and author time of commit + * + * @param committer Signature with committer and * commit time of commit + * + * @param message_encoding The encoding for the message in the + * commit, represented with a standard encoding name. + * E.g. "UTF-8". If NULL, no encoding header is written and + * UTF-8 is assumed. + * + * @param message Full message for this commit + * + * @param tree An instance of a `git_tree` object that will + * be used as the tree for the commit. This tree object must + * also be owned by the given `repo`. + * + * @return 0 or an error code + * The created commit will be written to the Object Database and + * the given reference will be updated to point to it */ GIT_EXTERN(int) git_commit_amend( git_oid *id, @@ -604,4 +671,5 @@ GIT_EXTERN(void) git_commitarray_dispose(git_commitarray *array); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/common.h b/include/git2/common.h index 8d0157044..56847e681 100644 --- a/include/git2/common.h +++ b/include/git2/common.h @@ -11,7 +11,9 @@ #include #ifdef __cplusplus + /** Start declarations in C mode for C++ compatibility */ # define GIT_BEGIN_DECL extern "C" { + /** End declarations in C mode */ # define GIT_END_DECL } #else /** Start declarations in C mode */ @@ -71,6 +73,7 @@ typedef size_t size_t; # define GIT_FORMAT_PRINTF(a,b) /* empty */ #endif +/** Defined when building on Windows (but not via cygwin) */ #if (defined(_WIN32)) && !defined(__CYGWIN__) #define GIT_WIN32 1 #endif @@ -81,9 +84,13 @@ typedef size_t size_t; /** * @file git2/common.h - * @brief Git common platform definitions + * @brief Base platform functionality * @defgroup git_common Git common platform definitions * @ingroup Git + * + * Common platform functionality including introspecting libgit2 + * itself - information like how it was built, and the current + * running version. * @{ */ @@ -538,7 +545,6 @@ typedef enum { * > to a remote server. Set to 0 to use the system default. * * @param option Option key - * @param ... value to set the option * @return 0 on success, <0 on failure */ GIT_EXTERN(int) git_libgit2_opts(int option, ...); diff --git a/include/git2/config.h b/include/git2/config.h index 9a425aa0b..f9c266754 100644 --- a/include/git2/config.h +++ b/include/git2/config.h @@ -13,9 +13,13 @@ /** * @file git2/config.h - * @brief Git config management routines + * @brief Per-repository, per-user or per-system configuration * @defgroup git_config Git config management routines * @ingroup Git + * + * Git configuration affects the operation of the version control + * system, and can be specified on a per-repository basis, in user + * settings, or at the system level. * @{ */ GIT_BEGIN_DECL @@ -38,37 +42,57 @@ GIT_BEGIN_DECL * * git_config_open_default() and git_repository_config() honor those * priority levels as well. + * + * @see git_config_open_default + * @see git_repository_config */ typedef enum { - /** System-wide on Windows, for compatibility with portable git */ + /** + * System-wide on Windows, for compatibility with "Portable Git". + */ GIT_CONFIG_LEVEL_PROGRAMDATA = 1, - /** System-wide configuration file; /etc/gitconfig on Linux systems */ + /** + * System-wide configuration file; `/etc/gitconfig` on Linux. + */ GIT_CONFIG_LEVEL_SYSTEM = 2, - /** XDG compatible configuration file; typically ~/.config/git/config */ + /** + * XDG compatible configuration file; typically + * `~/.config/git/config`. + */ GIT_CONFIG_LEVEL_XDG = 3, - /** User-specific configuration file (also called Global configuration - * file); typically ~/.gitconfig + /** + * Global configuration file is the user-specific configuration; + * typically `~/.gitconfig`. */ GIT_CONFIG_LEVEL_GLOBAL = 4, - /** Repository specific configuration file; $WORK_DIR/.git/config on - * non-bare repos + /** + * Local configuration, the repository-specific configuration file; + * typically `$GIT_DIR/config`. */ GIT_CONFIG_LEVEL_LOCAL = 5, - /** Worktree specific configuration file; $GIT_DIR/config.worktree + /** + * Worktree-specific configuration; typically + * `$GIT_DIR/config.worktree`. */ GIT_CONFIG_LEVEL_WORKTREE = 6, - /** Application specific configuration file; freely defined by applications + /** + * Application-specific configuration file. Callers into libgit2 + * can add their own configuration beginning at this level. */ GIT_CONFIG_LEVEL_APP = 7, - /** Represents the highest level available config file (i.e. the most - * specific config file available that actually is loaded) + /** + * Not a configuration level; callers can use this value when + * querying configuration levels to specify that they want to + * have data from the highest-level currently configuration. + * This can be used to indicate that callers want the most + * specific config file available that actually is loaded. */ GIT_CONFIG_HIGHEST_LEVEL = -1 } git_config_level_t; @@ -77,13 +101,13 @@ typedef enum { * An entry in a configuration file */ typedef struct git_config_entry { - /** Name of the configuration entry (normalized) */ + /** Name of the configuration entry (normalized). */ const char *name; - /** Literal (string) value of the entry */ + /** Literal (string) value of the entry. */ const char *value; - /** The type of backend that this entry exists in (eg, "file") */ + /** The type of backend that this entry exists in (eg, "file"). */ const char *backend_type; /** @@ -92,22 +116,22 @@ typedef struct git_config_entry { */ const char *origin_path; - /** Depth of includes where this variable was found */ + /** Depth of includes where this variable was found. */ unsigned int include_depth; - /** Configuration level for the file this was found in */ + /** Configuration level for the file this was found in. */ git_config_level_t level; } git_config_entry; /** - * Free a config entry + * Free a config entry. * * @param entry The entry to free. */ GIT_EXTERN(void) git_config_entry_free(git_config_entry *entry); /** - * A config enumeration callback + * A config enumeration callback. * * @param entry the entry currently being enumerated * @param payload a user-specified pointer @@ -116,7 +140,7 @@ GIT_EXTERN(void) git_config_entry_free(git_config_entry *entry); typedef int GIT_CALLBACK(git_config_foreach_cb)(const git_config_entry *entry, void *payload); /** - * An opaque structure for a configuration iterator + * An opaque structure for a configuration iterator. */ typedef struct git_config_iterator git_config_iterator; @@ -241,9 +265,9 @@ GIT_EXTERN(int) git_config_new(git_config **out); * @param cfg the configuration to add the file to * @param path path to the configuration file to add * @param level the priority level of the backend - * @param force replace config file at the given priority level * @param repo optional repository to allow parsing of * conditional includes + * @param force replace config file at the given priority level * @return 0 on success, GIT_EEXISTS when adding more than one file * for a given priority level (and force_replace set to 0), * GIT_ENOTFOUND when the file doesn't exist or error code @@ -305,6 +329,17 @@ GIT_EXTERN(int) git_config_open_level( */ GIT_EXTERN(int) git_config_open_global(git_config **out, git_config *config); +/** + * Set the write order for configuration backends. By default, the + * write ordering does not match the read ordering; for example, the + * worktree configuration is a high-priority for reading, but is not + * written to unless explicitly chosen. + * + * @param cfg the configuration to change write order of + * @param levels the ordering of levels for writing + * @param len the length of the levels array + * @return 0 or an error code + */ GIT_EXTERN(int) git_config_set_writeorder( git_config *cfg, git_config_level_t *levels, @@ -813,4 +848,5 @@ GIT_EXTERN(int) git_config_lock(git_transaction **tx, git_config *cfg); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/credential.h b/include/git2/credential.h index 7a04bc064..33755ca91 100644 --- a/include/git2/credential.h +++ b/include/git2/credential.h @@ -11,9 +11,12 @@ /** * @file git2/credential.h - * @brief Git authentication & credential management + * @brief Authentication and credential management * @defgroup git_credential Authentication & credential management * @ingroup Git + * + * Credentials specify how to authenticate to a remote system + * over HTTPS or SSH. * @{ */ GIT_BEGIN_DECL @@ -119,7 +122,7 @@ typedef struct git_credential_ssh_custom git_credential_ssh_custom; * an error. As such, it's easy to get in a loop if you fail to stop providing * the same incorrect credentials. * - * @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 username_from_url The username that was embedded in a "user\@host" * remote url, or NULL if not included. @@ -241,6 +244,18 @@ typedef struct _LIBSSH2_USERAUTH_KBDINT_PROMPT LIBSSH2_USERAUTH_KBDINT_PROMPT; typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE LIBSSH2_USERAUTH_KBDINT_RESPONSE; #endif +/** + * Callback for interactive SSH credentials. + * + * @param name the name + * @param name_len the length of the name + * @param instruction the authentication instruction + * @param instruction_len the length of the instruction + * @param num_prompts the number of prompts + * @param prompts the prompts + * @param responses the responses + * @param abstract the abstract + */ typedef void GIT_CALLBACK(git_credential_ssh_interactive_cb)( const char *name, int name_len, @@ -278,6 +293,18 @@ GIT_EXTERN(int) git_credential_ssh_key_from_agent( git_credential **out, const char *username); +/** + * Callback for credential signing. + * + * @param session the libssh2 session + * @param sig the signature + * @param sig_len the length of the signature + * @param data the data + * @param data_len the length of the data + * @param abstract the abstract + * @return 0 for success, < 0 to indicate an error, > 0 to indicate + * no credential was acquired + */ typedef int GIT_CALLBACK(git_credential_sign_cb)( LIBSSH2_SESSION *session, unsigned char **sig, size_t *sig_len, @@ -312,4 +339,5 @@ GIT_EXTERN(int) git_credential_ssh_custom_new( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/credential_helpers.h b/include/git2/credential_helpers.h index f0fb07041..706558d5b 100644 --- a/include/git2/credential_helpers.h +++ b/include/git2/credential_helpers.h @@ -50,4 +50,5 @@ GIT_EXTERN(int) git_credential_userpass( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/deprecated.h b/include/git2/deprecated.h index 49ac9c87f..b8b0238da 100644 --- a/include/git2/deprecated.h +++ b/include/git2/deprecated.h @@ -52,7 +52,7 @@ /** * @file git2/deprecated.h - * @brief libgit2 deprecated functions and values + * @brief Deprecated functions and values * @ingroup Git * @{ */ @@ -69,15 +69,23 @@ GIT_BEGIN_DECL */ /**@{*/ +/** @deprecated use GIT_ATTR_VALUE_UNSPECIFIED */ #define GIT_ATTR_UNSPECIFIED_T GIT_ATTR_VALUE_UNSPECIFIED +/** @deprecated use GIT_ATTR_VALUE_TRUE */ #define GIT_ATTR_TRUE_T GIT_ATTR_VALUE_TRUE +/** @deprecated use GIT_ATTR_VALUE_FALSE */ #define GIT_ATTR_FALSE_T GIT_ATTR_VALUE_FALSE +/** @deprecated use GIT_ATTR_VALUE_STRING */ #define GIT_ATTR_VALUE_T GIT_ATTR_VALUE_STRING +/** @deprecated use GIT_ATTR_IS_TRUE */ #define GIT_ATTR_TRUE(attr) GIT_ATTR_IS_TRUE(attr) +/** @deprecated use GIT_ATTR_IS_FALSE */ #define GIT_ATTR_FALSE(attr) GIT_ATTR_IS_FALSE(attr) +/** @deprecated use GIT_ATTR_IS_UNSPECIFIED */ #define GIT_ATTR_UNSPECIFIED(attr) GIT_ATTR_IS_UNSPECIFIED(attr) +/** @deprecated use git_attr_value_t */ typedef git_attr_value_t git_attr_t; /**@}*/ @@ -93,6 +101,7 @@ typedef git_attr_value_t git_attr_t; */ /**@{*/ +/** @deprecated use GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD */ #define GIT_BLOB_FILTER_ATTTRIBUTES_FROM_HEAD GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD GIT_EXTERN(int) git_blob_create_fromworkdir(git_oid *id, git_repository *repo, const char *relative_path); @@ -285,11 +294,16 @@ typedef int (*git_commit_signing_cb)( */ /**@{*/ +/** @deprecated use GIT_CONFIGMAP_FALSE */ #define GIT_CVAR_FALSE GIT_CONFIGMAP_FALSE +/** @deprecated use GIT_CONFIGMAP_TRUE */ #define GIT_CVAR_TRUE GIT_CONFIGMAP_TRUE +/** @deprecated use GIT_CONFIGMAP_INT32 */ #define GIT_CVAR_INT32 GIT_CONFIGMAP_INT32 +/** @deprecated use GIT_CONFIGMAP_STRING */ #define GIT_CVAR_STRING GIT_CONFIGMAP_STRING +/** @deprecated use git_cvar_map */ typedef git_configmap git_cvar_map; /**@}*/ @@ -314,11 +328,12 @@ typedef enum { /** Don't insert "[PATCH]" in the subject header*/ GIT_DIFF_FORMAT_EMAIL_EXCLUDE_SUBJECT_PATCH_MARKER = (1 << 0) - } git_diff_format_email_flags_t; /** * Options for controlling the formatting of the generated e-mail. + * + * @deprecated use `git_email_create_options` */ typedef struct { unsigned int version; @@ -345,7 +360,9 @@ typedef struct { const git_signature *author; } git_diff_format_email_options; +/** @deprecated use `git_email_create_options` */ #define GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION 1 +/** @deprecated use `git_email_create_options` */ #define GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT {GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION, 0, 1, 1, NULL, NULL, NULL, NULL} /** @@ -401,41 +418,75 @@ GIT_EXTERN(int) git_diff_format_email_options_init( */ /**@{*/ +/** @deprecated use `GIT_ERROR_NONE` */ #define GITERR_NONE GIT_ERROR_NONE +/** @deprecated use `GIT_ERROR_NOMEMORY` */ #define GITERR_NOMEMORY GIT_ERROR_NOMEMORY +/** @deprecated use `GIT_ERROR_OS` */ #define GITERR_OS GIT_ERROR_OS +/** @deprecated use `GIT_ERROR_INVALID` */ #define GITERR_INVALID GIT_ERROR_INVALID +/** @deprecated use `GIT_ERROR_REFERENCE` */ #define GITERR_REFERENCE GIT_ERROR_REFERENCE +/** @deprecated use `GIT_ERROR_ZLIB` */ #define GITERR_ZLIB GIT_ERROR_ZLIB +/** @deprecated use `GIT_ERROR_REPOSITORY` */ #define GITERR_REPOSITORY GIT_ERROR_REPOSITORY +/** @deprecated use `GIT_ERROR_CONFIG` */ #define GITERR_CONFIG GIT_ERROR_CONFIG +/** @deprecated use `GIT_ERROR_REGEX` */ #define GITERR_REGEX GIT_ERROR_REGEX +/** @deprecated use `GIT_ERROR_ODB` */ #define GITERR_ODB GIT_ERROR_ODB +/** @deprecated use `GIT_ERROR_INDEX` */ #define GITERR_INDEX GIT_ERROR_INDEX +/** @deprecated use `GIT_ERROR_OBJECT` */ #define GITERR_OBJECT GIT_ERROR_OBJECT +/** @deprecated use `GIT_ERROR_NET` */ #define GITERR_NET GIT_ERROR_NET +/** @deprecated use `GIT_ERROR_TAG` */ #define GITERR_TAG GIT_ERROR_TAG +/** @deprecated use `GIT_ERROR_TREE` */ #define GITERR_TREE GIT_ERROR_TREE +/** @deprecated use `GIT_ERROR_INDEXER` */ #define GITERR_INDEXER GIT_ERROR_INDEXER +/** @deprecated use `GIT_ERROR_SSL` */ #define GITERR_SSL GIT_ERROR_SSL +/** @deprecated use `GIT_ERROR_SUBMODULE` */ #define GITERR_SUBMODULE GIT_ERROR_SUBMODULE +/** @deprecated use `GIT_ERROR_THREAD` */ #define GITERR_THREAD GIT_ERROR_THREAD +/** @deprecated use `GIT_ERROR_STASH` */ #define GITERR_STASH GIT_ERROR_STASH +/** @deprecated use `GIT_ERROR_CHECKOUT` */ #define GITERR_CHECKOUT GIT_ERROR_CHECKOUT +/** @deprecated use `GIT_ERROR_FETCHHEAD` */ #define GITERR_FETCHHEAD GIT_ERROR_FETCHHEAD +/** @deprecated use `GIT_ERROR_MERGE` */ #define GITERR_MERGE GIT_ERROR_MERGE +/** @deprecated use `GIT_ERROR_SSH` */ #define GITERR_SSH GIT_ERROR_SSH +/** @deprecated use `GIT_ERROR_FILTER` */ #define GITERR_FILTER GIT_ERROR_FILTER +/** @deprecated use `GIT_ERROR_REVERT` */ #define GITERR_REVERT GIT_ERROR_REVERT +/** @deprecated use `GIT_ERROR_CALLBACK` */ #define GITERR_CALLBACK GIT_ERROR_CALLBACK +/** @deprecated use `GIT_ERROR_CHERRYPICK` */ #define GITERR_CHERRYPICK GIT_ERROR_CHERRYPICK +/** @deprecated use `GIT_ERROR_DESCRIBE` */ #define GITERR_DESCRIBE GIT_ERROR_DESCRIBE +/** @deprecated use `GIT_ERROR_REBASE` */ #define GITERR_REBASE GIT_ERROR_REBASE +/** @deprecated use `GIT_ERROR_FILESYSTEM` */ #define GITERR_FILESYSTEM GIT_ERROR_FILESYSTEM +/** @deprecated use `GIT_ERROR_PATCH` */ #define GITERR_PATCH GIT_ERROR_PATCH +/** @deprecated use `GIT_ERROR_WORKTREE` */ #define GITERR_WORKTREE GIT_ERROR_WORKTREE +/** @deprecated use `GIT_ERROR_SHA1` */ #define GITERR_SHA1 GIT_ERROR_SHA1 - +/** @deprecated use `GIT_ERROR_SHA` */ #define GIT_ERROR_SHA1 GIT_ERROR_SHA /** @@ -500,37 +551,63 @@ GIT_EXTERN(void) giterr_set_oom(void); */ /**@{*/ +/* The git_idxentry_extended_flag_t enum */ +/** @deprecated use `GIT_INDEX_ENTRY_NAMEMASK` */ #define GIT_IDXENTRY_NAMEMASK GIT_INDEX_ENTRY_NAMEMASK +/** @deprecated use `GIT_INDEX_ENTRY_STAGEMASK` */ #define GIT_IDXENTRY_STAGEMASK GIT_INDEX_ENTRY_STAGEMASK +/** @deprecated use `GIT_INDEX_ENTRY_STAGESHIFT` */ #define GIT_IDXENTRY_STAGESHIFT GIT_INDEX_ENTRY_STAGESHIFT /* The git_indxentry_flag_t enum */ +/** @deprecated use `GIT_INDEX_ENTRY_EXTENDED` */ #define GIT_IDXENTRY_EXTENDED GIT_INDEX_ENTRY_EXTENDED +/** @deprecated use `GIT_INDEX_ENTRY_VALID` */ #define GIT_IDXENTRY_VALID GIT_INDEX_ENTRY_VALID +/** @deprecated use `GIT_INDEX_ENTRY_STAGE` */ #define GIT_IDXENTRY_STAGE(E) GIT_INDEX_ENTRY_STAGE(E) +/** @deprecated use `GIT_INDEX_ENTRY_STAGE_SET` */ #define GIT_IDXENTRY_STAGE_SET(E,S) GIT_INDEX_ENTRY_STAGE_SET(E,S) /* The git_idxentry_extended_flag_t enum */ +/** @deprecated use `GIT_INDEX_ENTRY_INTENT_TO_ADD` */ #define GIT_IDXENTRY_INTENT_TO_ADD GIT_INDEX_ENTRY_INTENT_TO_ADD +/** @deprecated use `GIT_INDEX_ENTRY_SKIP_WORKTREE` */ #define GIT_IDXENTRY_SKIP_WORKTREE GIT_INDEX_ENTRY_SKIP_WORKTREE +/** @deprecated use `GIT_INDEX_ENTRY_INTENT_TO_ADD | GIT_INDEX_ENTRY_SKIP_WORKTREE` */ #define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_INDEX_ENTRY_INTENT_TO_ADD | GIT_INDEX_ENTRY_SKIP_WORKTREE) +/** @deprecated this value is not public */ #define GIT_IDXENTRY_EXTENDED2 (1 << 15) +/** @deprecated this value is not public */ #define GIT_IDXENTRY_UPDATE (1 << 0) +/** @deprecated this value is not public */ #define GIT_IDXENTRY_REMOVE (1 << 1) +/** @deprecated this value is not public */ #define GIT_IDXENTRY_UPTODATE (1 << 2) +/** @deprecated this value is not public */ #define GIT_IDXENTRY_ADDED (1 << 3) +/** @deprecated this value is not public */ #define GIT_IDXENTRY_HASHED (1 << 4) +/** @deprecated this value is not public */ #define GIT_IDXENTRY_UNHASHED (1 << 5) +/** @deprecated this value is not public */ #define GIT_IDXENTRY_WT_REMOVE (1 << 6) +/** @deprecated this value is not public */ #define GIT_IDXENTRY_CONFLICTED (1 << 7) +/** @deprecated this value is not public */ #define GIT_IDXENTRY_UNPACKED (1 << 8) +/** @deprecated this value is not public */ #define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9) /* The git_index_capability_t enum */ +/** @deprecated use `GIT_INDEX_CAPABILITY_IGNORE_CASE` */ #define GIT_INDEXCAP_IGNORE_CASE GIT_INDEX_CAPABILITY_IGNORE_CASE +/** @deprecated use `GIT_INDEX_CAPABILITY_NO_FILEMODE` */ #define GIT_INDEXCAP_NO_FILEMODE GIT_INDEX_CAPABILITY_NO_FILEMODE +/** @deprecated use `GIT_INDEX_CAPABILITY_NO_SYMLINKS` */ #define GIT_INDEXCAP_NO_SYMLINKS GIT_INDEX_CAPABILITY_NO_SYMLINKS +/** @deprecated use `GIT_INDEX_CAPABILITY_FROM_OWNER` */ #define GIT_INDEXCAP_FROM_OWNER GIT_INDEX_CAPABILITY_FROM_OWNER GIT_EXTERN(int) git_index_add_frombuffer( @@ -550,17 +627,28 @@ GIT_EXTERN(int) git_index_add_frombuffer( */ /**@{*/ +/** @deprecate use `git_object_t` */ #define git_otype git_object_t +/** @deprecate use `GIT_OBJECT_ANY` */ #define GIT_OBJ_ANY GIT_OBJECT_ANY +/** @deprecate use `GIT_OBJECT_INVALID` */ #define GIT_OBJ_BAD GIT_OBJECT_INVALID +/** @deprecated this value is not public */ #define GIT_OBJ__EXT1 0 +/** @deprecate use `GIT_OBJECT_COMMIT` */ #define GIT_OBJ_COMMIT GIT_OBJECT_COMMIT +/** @deprecate use `GIT_OBJECT_TREE` */ #define GIT_OBJ_TREE GIT_OBJECT_TREE +/** @deprecate use `GIT_OBJECT_BLOB` */ #define GIT_OBJ_BLOB GIT_OBJECT_BLOB +/** @deprecate use `GIT_OBJECT_TAG` */ #define GIT_OBJ_TAG GIT_OBJECT_TAG +/** @deprecated this value is not public */ #define GIT_OBJ__EXT2 5 +/** @deprecate use `GIT_OBJECT_OFS_DELTA` */ #define GIT_OBJ_OFS_DELTA GIT_OBJECT_OFS_DELTA +/** @deprecate use `GIT_OBJECT_REF_DELTA` */ #define GIT_OBJ_REF_DELTA GIT_OBJECT_REF_DELTA /** @@ -612,17 +700,27 @@ GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name); /**@{*/ /** Basic type of any Git reference. */ +/** @deprecate use `git_reference_t` */ #define git_ref_t git_reference_t +/** @deprecate use `git_reference_format_t` */ #define git_reference_normalize_t git_reference_format_t +/** @deprecate use `GIT_REFERENCE_INVALID` */ #define GIT_REF_INVALID GIT_REFERENCE_INVALID +/** @deprecate use `GIT_REFERENCE_DIRECT` */ #define GIT_REF_OID GIT_REFERENCE_DIRECT +/** @deprecate use `GIT_REFERENCE_SYMBOLIC` */ #define GIT_REF_SYMBOLIC GIT_REFERENCE_SYMBOLIC +/** @deprecate use `GIT_REFERENCE_ALL` */ #define GIT_REF_LISTALL GIT_REFERENCE_ALL +/** @deprecate use `GIT_REFERENCE_FORMAT_NORMAL` */ #define GIT_REF_FORMAT_NORMAL GIT_REFERENCE_FORMAT_NORMAL +/** @deprecate use `GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL` */ #define GIT_REF_FORMAT_ALLOW_ONELEVEL GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL +/** @deprecate use `GIT_REFERENCE_FORMAT_REFSPEC_PATTERN` */ #define GIT_REF_FORMAT_REFSPEC_PATTERN GIT_REFERENCE_FORMAT_REFSPEC_PATTERN +/** @deprecate use `GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND` */ #define GIT_REF_FORMAT_REFSPEC_SHORTHAND GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND /** @@ -663,8 +761,11 @@ GIT_EXTERN(int) git_tag_create_frombuffer( typedef git_revspec_t git_revparse_mode_t; +/** @deprecated use `GIT_REVSPEC_SINGLE` */ #define GIT_REVPARSE_SINGLE GIT_REVSPEC_SINGLE +/** @deprecated use `GIT_REVSPEC_RANGE` */ #define GIT_REVPARSE_RANGE GIT_REVSPEC_RANGE +/** @deprecated use `GIT_REVSPEC_MERGE_BASE` */ #define GIT_REVPARSE_MERGE_BASE GIT_REVSPEC_MERGE_BASE /**@}*/ @@ -693,14 +794,22 @@ typedef git_credential_sign_cb git_cred_sign_cb; typedef git_credential_ssh_interactive_cb git_cred_ssh_interactive_callback; typedef git_credential_ssh_interactive_cb git_cred_ssh_interactive_cb; +/** @deprecated use `git_credential_t` */ #define git_credtype_t git_credential_t +/** @deprecated use `GIT_CREDENTIAL_USERPASS_PLAINTEXT` */ #define GIT_CREDTYPE_USERPASS_PLAINTEXT GIT_CREDENTIAL_USERPASS_PLAINTEXT +/** @deprecated use `GIT_CREDENTIAL_SSH_KEY` */ #define GIT_CREDTYPE_SSH_KEY GIT_CREDENTIAL_SSH_KEY +/** @deprecated use `GIT_CREDENTIAL_SSH_CUSTOM` */ #define GIT_CREDTYPE_SSH_CUSTOM GIT_CREDENTIAL_SSH_CUSTOM +/** @deprecated use `GIT_CREDENTIAL_DEFAULT` */ #define GIT_CREDTYPE_DEFAULT GIT_CREDENTIAL_DEFAULT +/** @deprecated use `GIT_CREDENTIAL_SSH_INTERACTIVE` */ #define GIT_CREDTYPE_SSH_INTERACTIVE GIT_CREDENTIAL_SSH_INTERACTIVE +/** @deprecated use `GIT_CREDENTIAL_USERNAME` */ #define GIT_CREDTYPE_USERNAME GIT_CREDENTIAL_USERNAME +/** @deprecated use `GIT_CREDENTIAL_SSH_MEMORY` */ #define GIT_CREDTYPE_SSH_MEMORY GIT_CREDENTIAL_SSH_MEMORY GIT_EXTERN(void) git_cred_free(git_credential *cred); @@ -778,8 +887,11 @@ typedef git_trace_cb git_trace_callback; /**@{*/ #ifndef GIT_EXPERIMENTAL_SHA256 +/** Deprecated OID "raw size" definition */ # define GIT_OID_RAWSZ GIT_OID_SHA1_SIZE +/** Deprecated OID "hex size" definition */ # define GIT_OID_HEXSZ GIT_OID_SHA1_HEXSIZE +/** Deprecated OID "hex zero" definition */ # define GIT_OID_HEX_ZERO GIT_OID_SHA1_HEXZERO #endif diff --git a/include/git2/describe.h b/include/git2/describe.h index 7a796f130..938c470d2 100644 --- a/include/git2/describe.h +++ b/include/git2/describe.h @@ -13,10 +13,14 @@ /** * @file git2/describe.h - * @brief Git describing routines + * @brief Describe a commit in reference to tags * @defgroup git_describe Git describing routines * @ingroup Git * @{ + * + * Describe a commit, showing information about how the current commit + * relates to the tags. This can be useful for showing how the current + * commit has changed from a particular tagged version of the repository. */ GIT_BEGIN_DECL @@ -60,10 +64,15 @@ typedef struct git_describe_options { int show_commit_oid_as_fallback; } git_describe_options; +/** Default maximum candidate tags */ #define GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS 10 +/** Default abbreviated size */ #define GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE 7 +/** Current version for the `git_describe_options` structure */ #define GIT_DESCRIBE_OPTIONS_VERSION 1 + +/** Static constructor for `git_describe_options` */ #define GIT_DESCRIBE_OPTIONS_INIT { \ GIT_DESCRIBE_OPTIONS_VERSION, \ GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \ @@ -110,7 +119,10 @@ typedef struct { const char *dirty_suffix; } git_describe_format_options; +/** Current version for the `git_describe_format_options` structure */ #define GIT_DESCRIBE_FORMAT_OPTIONS_VERSION 1 + +/** Static constructor for `git_describe_format_options` */ #define GIT_DESCRIBE_FORMAT_OPTIONS_INIT { \ GIT_DESCRIBE_FORMAT_OPTIONS_VERSION, \ GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \ diff --git a/include/git2/diff.h b/include/git2/diff.h index 384b6e745..b12e8ab27 100644 --- a/include/git2/diff.h +++ b/include/git2/diff.h @@ -15,7 +15,7 @@ /** * @file git2/diff.h - * @brief Git tree and file differencing routines. + * @brief Indicate the differences between two versions of the repository * @ingroup Git * @{ */ @@ -342,6 +342,12 @@ typedef struct { * diff process continues. * - returns 0, the delta is inserted into the diff, and the diff process * continues. + * + * @param diff_so_far the diff structure as it currently exists + * @param delta_to_add the delta that is to be added + * @param matched_pathspec the pathspec + * @param payload the user-specified callback payload + * @return 0 on success, 1 to skip this delta, or an error code */ typedef int GIT_CALLBACK(git_diff_notify_cb)( const git_diff *diff_so_far, @@ -357,7 +363,8 @@ typedef int GIT_CALLBACK(git_diff_notify_cb)( * @param diff_so_far The diff being generated. * @param old_path The path to the old file or NULL. * @param new_path The path to the new file or NULL. - * @return Non-zero to abort the diff. + * @param payload the user-specified callback payload + * @return 0 or an error code */ typedef int GIT_CALLBACK(git_diff_progress_cb)( const git_diff *diff_so_far, @@ -463,10 +470,10 @@ typedef struct { const char *new_prefix; } git_diff_options; -/* The current version of the diff options structure */ +/** The current version of the diff options structure */ #define GIT_DIFF_OPTIONS_VERSION 1 -/* Stack initializer for diff options. Alternatively use +/** Stack initializer for diff options. Alternatively use * `git_diff_options_init` programmatic initialization. */ #define GIT_DIFF_OPTIONS_INIT \ @@ -492,12 +499,14 @@ GIT_EXTERN(int) git_diff_options_init( * @param delta A pointer to the delta data for the file * @param progress Goes from 0 to 1 over the diff * @param payload User-specified pointer from foreach function + * @return 0 or an error code */ typedef int GIT_CALLBACK(git_diff_file_cb)( const git_diff_delta *delta, float progress, void *payload); +/** Maximum size of the hunk header */ #define GIT_DIFF_HUNK_HEADER_SIZE 128 /** @@ -558,6 +567,11 @@ typedef struct { /** * When iterating over a diff, callback that will be made for * binary content within the diff. + * + * @param delta the delta + * @param binary the binary content + * @param payload the user-specified callback payload + * @return 0 or an error code */ typedef int GIT_CALLBACK(git_diff_binary_cb)( const git_diff_delta *delta, @@ -584,6 +598,11 @@ typedef struct { /** * When iterating over a diff, callback that will be made per hunk. + * + * @param delta the delta + * @param hunk the hunk + * @param payload the user-specified callback payload + * @return 0 or an error code */ typedef int GIT_CALLBACK(git_diff_hunk_cb)( const git_diff_delta *delta, @@ -645,6 +664,12 @@ typedef struct { * When printing a diff, callback that will be made to output each line * of text. This uses some extra GIT_DIFF_LINE_... constants for output * of lines of file and hunk headers. + * + * @param delta the delta that contains the line + * @param hunk the hunk that contains the line + * @param line the line in the diff + * @param payload the user-specified callback payload + * @return 0 or an error code */ typedef int GIT_CALLBACK(git_diff_line_cb)( const git_diff_delta *delta, /**< delta that contains this data */ @@ -802,7 +827,10 @@ typedef struct { git_diff_similarity_metric *metric; } git_diff_find_options; +/** Current version for the `git_diff_find_options` structure */ #define GIT_DIFF_FIND_OPTIONS_VERSION 1 + +/** Static constructor for `git_diff_find_options` */ #define GIT_DIFF_FIND_OPTIONS_INIT {GIT_DIFF_FIND_OPTIONS_VERSION} /** @@ -1296,10 +1324,10 @@ typedef struct { git_oid_t oid_type; } git_diff_parse_options; -/* The current version of the diff parse options structure */ +/** The current version of the diff parse options structure */ #define GIT_DIFF_PARSE_OPTIONS_VERSION 1 -/* Stack initializer for diff parse options. Alternatively use +/** Stack initializer for diff parse options. Alternatively use * `git_diff_parse_options_init` programmatic initialization. */ #define GIT_DIFF_PARSE_OPTIONS_INIT \ @@ -1432,7 +1460,10 @@ typedef struct git_diff_patchid_options { unsigned int version; } git_diff_patchid_options; +/** Current version for the `git_diff_patchid_options` structure */ #define GIT_DIFF_PATCHID_OPTIONS_VERSION 1 + +/** Static constructor for `git_diff_patchid_options` */ #define GIT_DIFF_PATCHID_OPTIONS_INIT { GIT_DIFF_PATCHID_OPTIONS_VERSION } /** @@ -1470,8 +1501,7 @@ GIT_EXTERN(int) git_diff_patchid_options_init( */ GIT_EXTERN(int) git_diff_patchid(git_oid *out, git_diff *diff, git_diff_patchid_options *opts); +/** @} */ GIT_END_DECL -/** @} */ - #endif diff --git a/include/git2/email.h b/include/git2/email.h index 08b573e8c..ad37e4249 100644 --- a/include/git2/email.h +++ b/include/git2/email.h @@ -12,7 +12,7 @@ /** * @file git2/email.h - * @brief Git email formatting and application routines. + * @brief Produce email-ready patches * @ingroup Git * @{ */ @@ -71,11 +71,14 @@ typedef struct { size_t reroll_number; } git_email_create_options; -/* +/** Current version for the `git_email_create_options` structure */ +#define GIT_EMAIL_CREATE_OPTIONS_VERSION 1 + +/** Static constructor for `git_email_create_options` + * * By default, our options include rename detection and binary * diffs to match `git format-patch`. */ -#define GIT_EMAIL_CREATE_OPTIONS_VERSION 1 #define GIT_EMAIL_CREATE_OPTIONS_INIT \ { \ GIT_EMAIL_CREATE_OPTIONS_VERSION, \ @@ -91,14 +94,14 @@ typedef struct { * @param out buffer to store the e-mail patch in * @param commit commit to create a patch for * @param opts email creation options + * @return 0 or an error code */ GIT_EXTERN(int) git_email_create_from_commit( git_buf *out, git_commit *commit, const git_email_create_options *opts); +/** @} */ GIT_END_DECL -/** @} */ - #endif diff --git a/include/git2/errors.h b/include/git2/errors.h index 52fa5f072..11413907e 100644 --- a/include/git2/errors.h +++ b/include/git2/errors.h @@ -11,7 +11,7 @@ /** * @file git2/errors.h - * @brief Git error handling routines and variables + * @brief Error handling routines and variables * @ingroup Git * @{ */ @@ -19,13 +19,20 @@ GIT_BEGIN_DECL /** Generic return codes */ typedef enum { - GIT_OK = 0, /**< No error */ + /** + * No error occurred; the call was successful. + */ + GIT_OK = 0, - GIT_ERROR = -1, /**< Generic error */ - GIT_ENOTFOUND = -3, /**< Requested object could not be found */ - GIT_EEXISTS = -4, /**< Object exists preventing operation */ - GIT_EAMBIGUOUS = -5, /**< More than one object matches */ - GIT_EBUFS = -6, /**< Output buffer too short to hold data */ + /** + * An error occurred; call `git_error_last` for more information. + */ + GIT_ERROR = -1, + + GIT_ENOTFOUND = -3, /**< Requested object could not be found. */ + GIT_EEXISTS = -4, /**< Object exists preventing operation. */ + GIT_EAMBIGUOUS = -5, /**< More than one object matches. */ + GIT_EBUFS = -6, /**< Output buffer too short to hold data. */ /** * GIT_EUSER is a special error that is never generated by libgit2 @@ -34,10 +41,10 @@ typedef enum { */ GIT_EUSER = -7, - GIT_EBAREREPO = -8, /**< Operation not allowed on bare repository */ - GIT_EUNBORNBRANCH = -9, /**< HEAD refers to branch with no commits */ - GIT_EUNMERGED = -10, /**< Merge in progress prevented operation */ - GIT_ENONFASTFORWARD = -11, /**< Reference was not fast-forwardable */ + GIT_EBAREREPO = -8, /**< Operation not allowed on bare repository. */ + GIT_EUNBORNBRANCH = -9, /**< HEAD refers to branch with no commits. */ + GIT_EUNMERGED = -10, /**< Merge in progress prevented operation */ + GIT_ENONFASTFORWARD = -11, /**< Reference was not fast-forwardable */ GIT_EINVALIDSPEC = -12, /**< Name/ref spec was not in a valid format */ GIT_ECONFLICT = -13, /**< Checkout conflicts prevented operation */ GIT_ELOCKED = -14, /**< Lock file prevented operation */ @@ -66,17 +73,9 @@ typedef enum { } git_error_code; /** - * Structure to store extra details of the last error that occurred. - * - * This is kept on a per-thread basis if GIT_THREADS was defined when the - * library was build, otherwise one is kept globally for the library + * Error classes are the category of error. They reflect the area of the + * code where an error occurred. */ -typedef struct { - char *message; - int klass; -} git_error; - -/** Error classes */ typedef enum { GIT_ERROR_NONE = 0, GIT_ERROR_NOMEMORY, @@ -117,6 +116,17 @@ typedef enum { GIT_ERROR_GRAFTS } git_error_t; +/** + * Structure to store extra details of the last error that occurred. + * + * This is kept on a per-thread basis if GIT_THREADS was defined when the + * library was build, otherwise one is kept globally for the library + */ +typedef struct { + char *message; /**< The error message for the last error. */ + int klass; /**< The category of the last error. @type git_error_t */ +} git_error; + /** * Return the last `git_error` object that was generated for the * current thread. @@ -134,10 +144,11 @@ typedef enum { * The memory for this object is managed by libgit2. It should not * be freed. * - * @return A git_error object. + * @return A pointer to a `git_error` object that describes the error. */ GIT_EXTERN(const git_error *) git_error_last(void); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/filter.h b/include/git2/filter.h index 79bf14ce5..cf6c5f59d 100644 --- a/include/git2/filter.h +++ b/include/git2/filter.h @@ -14,9 +14,15 @@ /** * @file git2/filter.h - * @brief Git filter APIs - * + * @brief Filters modify files during checkout or commit * @ingroup Git + * + * During checkout, filters update a file from a "canonical" state to + * a format appropriate for the local filesystem; during commit, filters + * produce the canonical state. For example, on Windows, the line ending + * filters _may_ take a canonical state (with Unix-style newlines) in + * the repository, and place the contents on-disk with Windows-style + * `\r\n` line endings. * @{ */ GIT_BEGIN_DECL @@ -79,8 +85,11 @@ typedef struct { git_oid attr_commit_id; } git_filter_options; - #define GIT_FILTER_OPTIONS_VERSION 1 - #define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION} +/** Current version for the `git_filter_options` structure */ +#define GIT_FILTER_OPTIONS_VERSION 1 + +/** Static constructor for `git_filter_options` */ +#define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION} /** * A filter that can transform file data @@ -268,9 +277,7 @@ GIT_EXTERN(int) git_filter_list_stream_blob( */ GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters); - +/** @} */ GIT_END_DECL -/** @} */ - #endif diff --git a/include/git2/global.h b/include/git2/global.h index 2a87e10c6..f15eb2d28 100644 --- a/include/git2/global.h +++ b/include/git2/global.h @@ -9,6 +9,12 @@ #include "common.h" +/** + * @file git2/global.h + * @brief libgit2 library initializer and shutdown functionality + * @ingroup Git + * @{ + */ GIT_BEGIN_DECL /** @@ -32,7 +38,7 @@ GIT_EXTERN(int) git_libgit2_init(void); * many times as `git_libgit2_init()` was called - it will return the * number of remainining initializations that have not been shutdown * (after this one). - * + * * @return the number of remaining initializations of the library, or an * error code. */ @@ -40,5 +46,6 @@ GIT_EXTERN(int) git_libgit2_shutdown(void); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/graph.h b/include/git2/graph.h index 56edb2f87..1792020a4 100644 --- a/include/git2/graph.h +++ b/include/git2/graph.h @@ -13,7 +13,7 @@ /** * @file git2/graph.h - * @brief Git graph traversal routines + * @brief Graph traversal routines * @defgroup git_revwalk Git graph traversal routines * @ingroup Git * @{ @@ -61,8 +61,8 @@ GIT_EXTERN(int) git_graph_descendant_of( * * @param repo the repository where the commits exist * @param commit a previously loaded commit - * @param length the number of commits in the provided `descendant_array` * @param descendant_array oids of the commits + * @param length the number of commits in the provided `descendant_array` * @return 1 if the given commit is an ancestor of any of the given potential * descendants, 0 if not, error code otherwise. */ @@ -74,4 +74,5 @@ GIT_EXTERN(int) git_graph_reachable_from_any( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/ignore.h b/include/git2/ignore.h index 4c441c633..730f2214b 100644 --- a/include/git2/ignore.h +++ b/include/git2/ignore.h @@ -10,6 +10,15 @@ #include "common.h" #include "types.h" +/** + * @file git2/ignore.h + * @brief Ignore particular untracked files + * @ingroup Git + * @{ + * + * When examining the repository status, git can optionally ignore + * specified untracked files. + */ GIT_BEGIN_DECL /** @@ -73,6 +82,7 @@ GIT_EXTERN(int) git_ignore_path_is_ignored( git_repository *repo, const char *path); +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/index.h b/include/git2/index.h index 6e806371b..9f3efe1fc 100644 --- a/include/git2/index.h +++ b/include/git2/index.h @@ -15,9 +15,14 @@ /** * @file git2/index.h - * @brief Git index parsing and manipulation routines + * @brief Index (aka "cache" aka "staging area") * @defgroup git_index Git index parsing and manipulation routines * @ingroup Git + * + * The index (or "cache", or "staging area") is the contents of the + * next commit. In addition, the index stores other data, such as + * conflicts that occurred during the last merge operation, and + * the "treecache" to speed up various on-disk operations. * @{ */ GIT_BEGIN_DECL @@ -77,8 +82,11 @@ typedef struct git_index_entry { * data in the `flags`. */ +/** Mask for name length */ #define GIT_INDEX_ENTRY_NAMEMASK (0x0fff) +/** Mask for index entry stage */ #define GIT_INDEX_ENTRY_STAGEMASK (0x3000) +/** Shift bits for index entry */ #define GIT_INDEX_ENTRY_STAGESHIFT 12 /** @@ -89,9 +97,17 @@ typedef enum { GIT_INDEX_ENTRY_VALID = (0x8000) } git_index_entry_flag_t; +/** + * Macro to get the stage value (0 for the "main index", or a conflict + * value) from an index entry. + */ #define GIT_INDEX_ENTRY_STAGE(E) \ (((E)->flags & GIT_INDEX_ENTRY_STAGEMASK) >> GIT_INDEX_ENTRY_STAGESHIFT) +/** + * Macro to set the stage value (0 for the "main index", or a conflict + * value) for an index entry. + */ #define GIT_INDEX_ENTRY_STAGE_SET(E,S) do { \ (E)->flags = ((E)->flags & ~GIT_INDEX_ENTRY_STAGEMASK) | \ (((S) & 0x03) << GIT_INDEX_ENTRY_STAGESHIFT); } while (0) @@ -131,7 +147,14 @@ typedef enum { } git_index_capability_t; -/** Callback for APIs that add/remove/update files matching pathspec */ +/** + * Callback for APIs that add/remove/update files matching pathspec + * + * @param path the path + * @param matched_pathspec the given pathspec + * @param payload the user-specified payload + * @return 0 to continue with the index operation, positive number to skip this file for the index operation, negative number on failure + */ typedef int GIT_CALLBACK(git_index_matched_path_cb)( const char *path, const char *matched_pathspec, void *payload); @@ -166,6 +189,30 @@ typedef enum { GIT_INDEX_STAGE_THEIRS = 3 } git_index_stage_t; +#ifdef GIT_EXPERIMENTAL_SHA256 + +/** + * Creates a new bare Git index object, without a repository to back + * it. This index object is capable of storing SHA256 objects. + * + * @param index_out the pointer for the new index + * @param index_path the path to the index file in disk + * @param oid_type the object ID type to use for the repository + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_open(git_index **index_out, const char *index_path, git_oid_t oid_type); + +/** + * Create an in-memory index object. + * + * @param index_out the pointer for the new index + * @param oid_type the object ID type to use for the repository + * @return 0 or an error code + */ +GIT_EXTERN(int) git_index_new(git_index **index_out, git_oid_t oid_type); + +#else + /** * Create a new bare Git index object as a memory representation * of the Git index file in 'index_path', without a repository @@ -180,16 +227,11 @@ typedef enum { * * The index must be freed once it's no longer in use. * - * @param out the pointer for the new index + * @param index_out the pointer for the new index * @param index_path the path to the index file in disk * @return 0 or an error code */ - -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path, git_oid_t oid_type); -#else -GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path); -#endif +GIT_EXTERN(int) git_index_open(git_index **index_out, const char *index_path); /** * Create an in-memory index object. @@ -199,13 +241,11 @@ GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path); * * The index must be freed once it's no longer in use. * - * @param out the pointer for the new index + * @param index_out the pointer for the new index * @return 0 or an error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_index_new(git_index **out, git_oid_t oid_type); -#else -GIT_EXTERN(int) git_index_new(git_index **out); +GIT_EXTERN(int) git_index_new(git_index **index_out); + #endif /** @@ -845,4 +885,5 @@ GIT_EXTERN(void) git_index_conflict_iterator_free( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/indexer.h b/include/git2/indexer.h index 630eef934..d47ce2c18 100644 --- a/include/git2/indexer.h +++ b/include/git2/indexer.h @@ -4,13 +4,23 @@ * This file is part of libgit2, distributed under the GNU GPL v2 with * a Linking Exception. For full terms see the included COPYING file. */ -#ifndef _INCLUDE_git_indexer_h__ -#define _INCLUDE_git_indexer_h__ +#ifndef INCLUDE_git_indexer_h__ +#define INCLUDE_git_indexer_h__ #include "common.h" #include "types.h" #include "oid.h" +/** + * @file git2/indexer.h + * @brief Packfile indexing + * @ingroup Git + * @{ + * + * Indexing is the operation of taking a packfile - which is simply a + * collection of unordered commits - and producing an "index" so that + * one can lookup a commit in the packfile by object ID. + */ GIT_BEGIN_DECL /** A git indexer object */ @@ -53,6 +63,7 @@ typedef struct git_indexer_progress { * * @param stats Structure containing information about the state of the transfer * @param payload Payload provided by caller + * @return 0 on success or an error code */ typedef int GIT_CALLBACK(git_indexer_progress_cb)(const git_indexer_progress *stats, void *payload); @@ -85,7 +96,10 @@ typedef struct git_indexer_options { unsigned char verify; } git_indexer_options; +/** Current version for the `git_indexer_options` structure */ #define GIT_INDEXER_OPTIONS_VERSION 1 + +/** Static constructor for `git_indexer_options` */ #define GIT_INDEXER_OPTIONS_INIT { GIT_INDEXER_OPTIONS_VERSION } /** @@ -190,6 +204,7 @@ GIT_EXTERN(const char *) git_indexer_name(const git_indexer *idx); */ GIT_EXTERN(void) git_indexer_free(git_indexer *idx); +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/mailmap.h b/include/git2/mailmap.h index 7c3f60fcc..fd6ae7170 100644 --- a/include/git2/mailmap.h +++ b/include/git2/mailmap.h @@ -13,10 +13,15 @@ /** * @file git2/mailmap.h - * @brief Mailmap parsing routines + * @brief Mailmaps provide alternate email addresses for users * @defgroup git_mailmap Git mailmap routines * @ingroup Git * @{ + * + * A mailmap can be used to specify alternate email addresses for + * repository committers or authors. This allows systems to map + * commits made using different email addresses to the same logical + * person. */ GIT_BEGIN_DECL @@ -112,4 +117,5 @@ GIT_EXTERN(int) git_mailmap_resolve_signature( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/merge.h b/include/git2/merge.h index 11f84f1fb..be3b065b8 100644 --- a/include/git2/merge.h +++ b/include/git2/merge.h @@ -17,9 +17,12 @@ /** * @file git2/merge.h - * @brief Git merge routines + * @brief Merge re-joins diverging branches of history * @defgroup git_merge Git merge routines * @ingroup Git + * + * Merge will take two commits and attempt to produce a commit that + * includes the changes that were made in both branches. * @{ */ GIT_BEGIN_DECL @@ -45,7 +48,10 @@ typedef struct { unsigned int mode; } git_merge_file_input; +/** Current version for the `git_merge_file_input_options` structure */ #define GIT_MERGE_FILE_INPUT_VERSION 1 + +/** Static constructor for `git_merge_file_input_options` */ #define GIT_MERGE_FILE_INPUT_INIT {GIT_MERGE_FILE_INPUT_VERSION} /** @@ -180,6 +186,7 @@ typedef enum { GIT_MERGE_FILE_ACCEPT_CONFLICTS = (1 << 9) } git_merge_file_flag_t; +/** Default size for conflict markers */ #define GIT_MERGE_CONFLICT_MARKER_SIZE 7 /** @@ -217,7 +224,10 @@ typedef struct { unsigned short marker_size; } git_merge_file_options; +/** Current version for the `git_merge_file_options` structure */ #define GIT_MERGE_FILE_OPTIONS_VERSION 1 + +/** Static constructor for `git_merge_file_options` */ #define GIT_MERGE_FILE_OPTIONS_INIT {GIT_MERGE_FILE_OPTIONS_VERSION} /** @@ -312,7 +322,10 @@ typedef struct { uint32_t file_flags; } git_merge_options; +/** Current version for the `git_merge_options` structure */ #define GIT_MERGE_OPTIONS_VERSION 1 + +/** Static constructor for `git_merge_options` */ #define GIT_MERGE_OPTIONS_INIT { \ GIT_MERGE_OPTIONS_VERSION, GIT_MERGE_FIND_RENAMES } @@ -654,4 +667,5 @@ GIT_EXTERN(int) git_merge( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/message.h b/include/git2/message.h index cd3ddf730..874d027f2 100644 --- a/include/git2/message.h +++ b/include/git2/message.h @@ -12,7 +12,7 @@ /** * @file git2/message.h - * @brief Git message management routines + * @brief Commit messages * @ingroup Git * @{ */ @@ -83,4 +83,4 @@ GIT_EXTERN(void) git_message_trailer_array_free(git_message_trailer_array *arr); /** @} */ GIT_END_DECL -#endif /* INCLUDE_git_message_h__ */ +#endif diff --git a/include/git2/net.h b/include/git2/net.h index 8103eafbf..93bdac499 100644 --- a/include/git2/net.h +++ b/include/git2/net.h @@ -13,12 +13,13 @@ /** * @file git2/net.h - * @brief Git networking declarations + * @brief Low-level networking functionality * @ingroup Git * @{ */ GIT_BEGIN_DECL +/** Default git protocol port number */ #define GIT_DEFAULT_PORT "9418" /** @@ -51,4 +52,5 @@ struct git_remote_head { /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/notes.h b/include/git2/notes.h index c135881a7..3784d5f52 100644 --- a/include/git2/notes.h +++ b/include/git2/notes.h @@ -11,7 +11,7 @@ /** * @file git2/notes.h - * @brief Git notes management routines + * @brief Notes are metadata attached to an object * @defgroup git_note Git notes management routines * @ingroup Git * @{ @@ -21,13 +21,15 @@ GIT_BEGIN_DECL /** * Callback for git_note_foreach. * - * Receives: - * - blob_id: Oid of the blob containing the message - * - annotated_object_id: Oid of the git object being annotated - * - payload: Payload data passed to `git_note_foreach` + * @param blob_id object id of the blob containing the message + * @param annotated_object_id the id of the object being annotated + * @param payload user-specified data to the foreach function + * @return 0 on success, or a negative number on failure */ typedef int GIT_CALLBACK(git_note_foreach_cb)( - const git_oid *blob_id, const git_oid *annotated_object_id, void *payload); + const git_oid *blob_id, + const git_oid *annotated_object_id, + void *payload); /** * note iterator @@ -303,4 +305,5 @@ GIT_EXTERN(int) git_note_foreach( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/object.h b/include/git2/object.h index 6384aaa6e..8a50239fe 100644 --- a/include/git2/object.h +++ b/include/git2/object.h @@ -14,13 +14,14 @@ /** * @file git2/object.h - * @brief Git revision object management routines + * @brief Objects are blobs (files), trees (directories), commits, and annotated tags * @defgroup git_object Git revision object management routines * @ingroup Git * @{ */ GIT_BEGIN_DECL +/** Maximum size of a git object */ #define GIT_OBJECT_SIZE_MAX UINT64_MAX /** @@ -53,18 +54,18 @@ GIT_EXTERN(int) git_object_lookup( * * The object obtained will be so that its identifier * matches the first 'len' hexadecimal characters - * (packets of 4 bits) of the given 'id'. - * 'len' must be at least GIT_OID_MINPREFIXLEN, and - * long enough to identify a unique object matching - * the prefix; otherwise the method will fail. + * (packets of 4 bits) of the given `id`. `len` must be + * at least `GIT_OID_MINPREFIXLEN`, and long enough to + * identify a unique object matching the prefix; otherwise + * the method will fail. * * The generated reference is owned by the repository and * should be closed with the `git_object_free` method * instead of free'd manually. * - * The 'type' parameter must match the type of the object + * The `type` parameter must match the type of the object * in the odb; the method will fail otherwise. - * The special value 'GIT_OBJECT_ANY' may be passed to let + * The special value `GIT_OBJECT_ANY` may be passed to let * the method guess the object's type. * * @param object_out pointer where to store the looked-up object @@ -260,7 +261,7 @@ GIT_EXTERN(int) git_object_rawcontent_is_valid( * @warning This function is experimental and its signature may change in * the future. * - * @param valid Output pointer to set with validity of the object content + * @param[out] valid Output pointer to set with validity of the object content * @param buf The contents to validate * @param len The length of the buffer * @param object_type The type of the object in the buffer diff --git a/include/git2/odb.h b/include/git2/odb.h index 4a7af07b8..e809c36d7 100644 --- a/include/git2/odb.h +++ b/include/git2/odb.h @@ -15,7 +15,7 @@ /** * @file git2/odb.h - * @brief Git object database routines + * @brief An object database manages the storage of git objects * @defgroup git_odb Git object database routines * @ingroup Git * @{ @@ -35,6 +35,10 @@ typedef enum { /** * Function type for callbacks from git_odb_foreach. + * + * @param id an id of an object in the object database + * @param payload the payload from the initial call to git_odb_foreach + * @return 0 on success, or an error code */ typedef int GIT_CALLBACK(git_odb_foreach_cb)(const git_oid *id, void *payload); @@ -49,30 +53,53 @@ typedef struct { git_oid_t oid_type; } git_odb_options; -/* The current version of the diff options structure */ +/** The current version of the diff options structure */ #define GIT_ODB_OPTIONS_VERSION 1 -/* Stack initializer for odb options. Alternatively use +/** + * Stack initializer for odb options. Alternatively use * `git_odb_options_init` programmatic initialization. */ #define GIT_ODB_OPTIONS_INIT { GIT_ODB_OPTIONS_VERSION } +#ifdef GIT_EXPERIMENTAL_SHA256 + +/** + * Create a new object database with no backends. + * + * @param[out] odb location to store the database pointer, if opened. + * @param opts the options for this object database or NULL for defaults + * @return 0 or an error code + */ +GIT_EXTERN(int) git_odb_new(git_odb **odb, const git_odb_options *opts); + +/** + * Create a new object database and automatically add loose and packed + * backends. + * + * @param[out] odb_out location to store the database pointer, if opened. + * Set to NULL if the open failed. + * @param objects_dir path of the backends' "objects" directory. + * @param opts the options for this object database or NULL for defaults + * @return 0 or an error code + */ +GIT_EXTERN(int) git_odb_open( + git_odb **odb_out, + const char *objects_dir, + const git_odb_options *opts); + +#else + /** * Create a new object database with no backends. * * Before the ODB can be used for read/writing, a custom database * backend must be manually added using `git_odb_add_backend()` * - * @param out location to store the database pointer, if opened. - * Set to NULL if the open failed. - * @param opts the options for this object database or NULL for defaults + * @param[out] odb location to store the database pointer, if opened. * @return 0 or an error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_new(git_odb **out, const git_odb_options *opts); -#else -GIT_EXTERN(int) git_odb_new(git_odb **out); -#endif +GIT_EXTERN(int) git_odb_new(git_odb **odb); /** * Create a new object database and automatically add @@ -85,19 +112,12 @@ GIT_EXTERN(int) git_odb_new(git_odb **out); * assuming `objects_dir` as the Objects folder which * contains a 'pack/' folder with the corresponding data * - * @param out location to store the database pointer, if opened. + * @param[out] odb_out location to store the database pointer, if opened. * Set to NULL if the open failed. * @param objects_dir path of the backends' "objects" directory. - * @param opts the options for this object database or NULL for defaults * @return 0 or an error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_open( - git_odb **out, - const char *objects_dir, - const git_odb_options *opts); -#else -GIT_EXTERN(int) git_odb_open(git_odb **out, const char *objects_dir); +GIT_EXTERN(int) git_odb_open(git_odb **odb_out, const char *objects_dir); #endif /** @@ -134,13 +154,13 @@ GIT_EXTERN(void) git_odb_free(git_odb *db); * internally cached, so it should be closed * by the user once it's no longer in use. * - * @param out pointer where to store the read object + * @param[out] obj pointer where to store the read object * @param db database to search for the object in. * @param id identity of the object to read. * @return 0 if the object was read, GIT_ENOTFOUND if the object is * not in the database. */ -GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *id); +GIT_EXTERN(int) git_odb_read(git_odb_object **obj, git_odb *db, const git_oid *id); /** * Read an object from the database, given a prefix @@ -160,7 +180,7 @@ GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *i * internally cached, so it should be closed * by the user once it's no longer in use. * - * @param out pointer where to store the read object + * @param[out] obj pointer where to store the read object * @param db database to search for the object in. * @param short_id a prefix of the id of the object to read. * @param len the length of the prefix @@ -168,7 +188,7 @@ GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *i * database. GIT_EAMBIGUOUS if the prefix is ambiguous * (several objects match the prefix) */ -GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git_oid *short_id, size_t len); +GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **obj, git_odb *db, const git_oid *short_id, size_t len); /** * Read the header of an object from the database, without @@ -180,8 +200,8 @@ GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git * of an object, so the whole object will be read and then the * header will be returned. * - * @param len_out pointer where to store the length - * @param type_out pointer where to store the type + * @param[out] len_out pointer where to store the length + * @param[out] type_out pointer where to store the type * @param db database to search for the object in. * @param id identity of the object to read. * @return 0 if the object was read, GIT_ENOTFOUND if the object is not @@ -301,7 +321,10 @@ GIT_EXTERN(int) git_odb_refresh(git_odb *db); * @param payload data to pass to the callback * @return 0 on success, non-zero callback return value, or error code */ -GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payload); +GIT_EXTERN(int) git_odb_foreach( + git_odb *db, + git_odb_foreach_cb cb, + void *payload); /** * Write an object directly into the ODB @@ -316,7 +339,7 @@ GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payloa * * @param out pointer to store the OID result of the write * @param odb object database where to store the object - * @param data buffer with the data to store + * @param data @type `const unsigned char *` buffer with the data to store * @param len size of the buffer * @param type type of the data to store * @return 0 or an error code @@ -466,29 +489,54 @@ GIT_EXTERN(int) git_odb_write_pack( GIT_EXTERN(int) git_odb_write_multi_pack_index( git_odb *db); +#ifdef GIT_EXPERIMENTAL_SHA256 + /** - * Determine the object-ID (sha1 or sha256 hash) of a data buffer + * Generate the object ID (in SHA1 or SHA256 format) for a given data buffer. * - * The resulting OID will be the identifier for the data buffer as if - * the data buffer it were to written to the ODB. - * - * @param out the resulting object-ID. + * @param[out] oid the resulting object ID. * @param data data to hash * @param len size of the data * @param object_type of the data to hash * @param oid_type the oid type to hash to * @return 0 or an error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 GIT_EXTERN(int) git_odb_hash( - git_oid *out, + git_oid *oid, const void *data, size_t len, git_object_t object_type, git_oid_t oid_type); + +/** + * Determine the object ID of a file on disk. + * + * @param[out] oid oid structure the result is written into. + * @param path file to read and determine object id for + * @param object_type of the data to hash + * @param oid_type the oid type to hash to + * @return 0 or an error code + */ +GIT_EXTERN(int) git_odb_hashfile( + git_oid *oid, + const char *path, + git_object_t object_type, + git_oid_t oid_type); #else -GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_object_t type); -#endif + +/** + * Determine the object-ID (sha1 or sha256 hash) of a data buffer + * + * The resulting OID will be the identifier for the data buffer as if + * the data buffer it were to written to the ODB. + * + * @param[out] oid the resulting object-ID. + * @param data data to hash + * @param len size of the data + * @param object_type of the data to hash + * @return 0 or an error code + */ +GIT_EXTERN(int) git_odb_hash(git_oid *oid, const void *data, size_t len, git_object_t object_type); /** * Read a file from disk and fill a git_oid with the object id @@ -498,20 +546,13 @@ GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_obj * the `-w` flag, however, with the --no-filters flag. * If you need filters, see git_repository_hashfile. * - * @param out oid structure the result is written into. + * @param[out] oid oid structure the result is written into. * @param path file to read and determine object id for * @param object_type of the data to hash - * @param oid_type the oid type to hash to * @return 0 or an error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_hashfile( - git_oid *out, - const char *path, - git_object_t object_type, - git_oid_t oid_type); -#else -GIT_EXTERN(int) git_odb_hashfile(git_oid *out, const char *path, git_object_t type); +GIT_EXTERN(int) git_odb_hashfile(git_oid *oid, const char *path, git_object_t object_type); + #endif /** @@ -557,7 +598,7 @@ GIT_EXTERN(const git_oid *) git_odb_object_id(git_odb_object *object); * This pointer is owned by the object and shall not be free'd. * * @param object the object - * @return a pointer to the data + * @return @type `const unsigned char *` a pointer to the data */ GIT_EXTERN(const void *) git_odb_object_data(git_odb_object *object); @@ -651,4 +692,5 @@ GIT_EXTERN(int) git_odb_set_commit_graph(git_odb *odb, git_commit_graph *cgraph) /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/odb_backend.h b/include/git2/odb_backend.h index 12dd0fd38..88ca29fb9 100644 --- a/include/git2/odb_backend.h +++ b/include/git2/odb_backend.h @@ -13,17 +13,13 @@ /** * @file git2/backend.h - * @brief Git custom backend functions + * @brief Object database backends manage the storage of git objects * @defgroup git_odb Git object database routines * @ingroup Git * @{ */ GIT_BEGIN_DECL -/* - * Constructors for in-box ODB backends. - */ - /** Options for configuring a packfile object backend. */ typedef struct { unsigned int version; /**< version for the struct */ @@ -35,56 +31,16 @@ typedef struct { git_oid_t oid_type; } git_odb_backend_pack_options; -/* The current version of the diff options structure */ +/** The current version of the diff options structure */ #define GIT_ODB_BACKEND_PACK_OPTIONS_VERSION 1 -/* Stack initializer for odb pack backend options. Alternatively use +/** + * Stack initializer for odb pack backend options. Alternatively use * `git_odb_backend_pack_options_init` programmatic initialization. */ #define GIT_ODB_BACKEND_PACK_OPTIONS_INIT \ { GIT_ODB_BACKEND_PACK_OPTIONS_VERSION } -/** - * Create a backend for the packfiles. - * - * @param out location to store the odb backend pointer - * @param objects_dir the Git repository's objects directory - * - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_backend_pack( - git_odb_backend **out, - const char *objects_dir, - const git_odb_backend_pack_options *opts); -#else -GIT_EXTERN(int) git_odb_backend_pack( - git_odb_backend **out, - const char *objects_dir); -#endif - -/** - * Create a backend out of a single packfile - * - * This can be useful for inspecting the contents of a single - * packfile. - * - * @param out location to store the odb backend pointer - * @param index_file path to the packfile's .idx file - * - * @return 0 or an error code - */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_odb_backend_one_pack( - git_odb_backend **out, - const char *index_file, - const git_odb_backend_pack_options *opts); -#else -GIT_EXTERN(int) git_odb_backend_one_pack( - git_odb_backend **out, - const char *index_file); -#endif - typedef enum { GIT_ODB_BACKEND_LOOSE_FSYNC = (1 << 0) } git_odb_backend_loose_flag_t; @@ -118,30 +74,100 @@ typedef struct { git_oid_t oid_type; } git_odb_backend_loose_options; -/* The current version of the diff options structure */ +/** The current version of the diff options structure */ #define GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION 1 -/* Stack initializer for odb loose backend options. Alternatively use +/** + * Stack initializer for odb loose backend options. Alternatively use * `git_odb_backend_loose_options_init` programmatic initialization. */ #define GIT_ODB_BACKEND_LOOSE_OPTIONS_INIT \ { GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION, 0, -1 } +/* + * Constructors for in-box ODB backends. + */ + +#ifdef GIT_EXPERIMENTAL_SHA256 + +/** + * Create a backend for a directory containing packfiles. + * + * @param[out] out location to store the odb backend pointer + * @param objects_dir the Git repository's objects directory + * @param opts the options to use when creating the pack backend + * @return 0 or an error code + */ +GIT_EXTERN(int) git_odb_backend_pack( + git_odb_backend **out, + const char *objects_dir, + const git_odb_backend_pack_options *opts); + +/** + * Create a backend for a single packfile. + * + * @param[out] out location to store the odb backend pointer + * @param index_file path to the packfile's .idx file + * @param opts the options to use when creating the pack backend + * @return 0 or an error code + */ +GIT_EXTERN(int) git_odb_backend_one_pack( + git_odb_backend **out, + const char *index_file, + const git_odb_backend_pack_options *opts); + /** * Create a backend for loose objects * - * @param out location to store the odb backend pointer + * @param[out] out location to store the odb backend pointer * @param objects_dir the Git repository's objects directory * @param opts options for the loose object backend or NULL * * @return 0 or an error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 GIT_EXTERN(int) git_odb_backend_loose( git_odb_backend **out, const char *objects_dir, git_odb_backend_loose_options *opts); + #else + +/** + * Create a backend for a directory containing packfiles. + * + * @param[out] out location to store the odb backend pointer + * @param objects_dir the Git repository's objects directory + * @return 0 or an error code + */ +GIT_EXTERN(int) git_odb_backend_pack( + git_odb_backend **out, + const char *objects_dir); + +/** + * Create a backend out of a single packfile + * + * This can be useful for inspecting the contents of a single + * packfile. + * + * @param[out] out location to store the odb backend pointer + * @param index_file path to the packfile's .idx file + * @return 0 or an error code + */ +GIT_EXTERN(int) git_odb_backend_one_pack( + git_odb_backend **out, + const char *index_file); + +/** + * Create a backend for loose objects + * + * @param[out] out location to store the odb backend pointer + * @param objects_dir the Git repository's objects directory + * @param compression_level zlib compression level (0-9), or -1 for the default + * @param do_fsync if non-zero, perform an fsync on write + * @param dir_mode permission to use when creating directories, or 0 for default + * @param file_mode permission to use when creating directories, or 0 for default + * @return 0 or an error code + */ GIT_EXTERN(int) git_odb_backend_loose( git_odb_backend **out, const char *objects_dir, @@ -149,6 +175,7 @@ GIT_EXTERN(int) git_odb_backend_loose( int do_fsync, unsigned int dir_mode, unsigned int file_mode); + #endif /** Streaming mode */ @@ -218,6 +245,7 @@ struct git_odb_writepack { void GIT_CALLBACK(free)(git_odb_writepack *writepack); }; +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/oid.h b/include/git2/oid.h index 35b43ef18..0af9737a0 100644 --- a/include/git2/oid.h +++ b/include/git2/oid.h @@ -13,7 +13,7 @@ /** * @file git2/oid.h - * @brief Git object id routines + * @brief Object IDs * @defgroup git_oid Git object id routines * @ingroup Git * @{ @@ -82,13 +82,18 @@ typedef enum { #endif -/* Maximum possible object ID size in raw / hex string format. */ -#ifndef GIT_EXPERIMENTAL_SHA256 -# define GIT_OID_MAX_SIZE GIT_OID_SHA1_SIZE -# define GIT_OID_MAX_HEXSIZE GIT_OID_SHA1_HEXSIZE -#else +/** Maximum possible object ID size in raw format */ +#ifdef GIT_EXPERIMENTAL_SHA256 # define GIT_OID_MAX_SIZE GIT_OID_SHA256_SIZE +#else +# define GIT_OID_MAX_SIZE GIT_OID_SHA1_SIZE +#endif + +/** Maximum possible object ID size in hex format */ +#ifdef GIT_EXPERIMENTAL_SHA256 # define GIT_OID_MAX_HEXSIZE GIT_OID_SHA256_HEXSIZE +#else +# define GIT_OID_MAX_HEXSIZE GIT_OID_SHA1_HEXSIZE #endif /** Minimum length (in number of hex characters, @@ -107,6 +112,15 @@ typedef struct git_oid { unsigned char id[GIT_OID_MAX_SIZE]; } git_oid; +#ifdef GIT_EXPERIMENTAL_SHA256 + +GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str, git_oid_t type); +GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str, git_oid_t type); +GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length, git_oid_t type); +GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw, git_oid_t type); + +#else + /** * Parse a hex formatted object id into a git_oid. * @@ -119,28 +133,18 @@ typedef struct git_oid { * the hex sequence and have at least the number of bytes * needed for an oid encoded in hex (40 bytes for sha1, * 256 bytes for sha256). - * @param type the type of object id * @return 0 or an error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str, git_oid_t type); -#else GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str); -#endif /** * Parse a hex formatted NUL-terminated string into a git_oid. * * @param out oid structure the result is written into. * @param str input hex string; must be null-terminated. - * @param type the type of object id * @return 0 or an error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str, git_oid_t type); -#else GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str); -#endif /** * Parse N characters of a hex formatted object id into a git_oid. @@ -151,14 +155,9 @@ GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str); * @param out oid structure the result is written into. * @param str input hex string of at least size `length` * @param length length of the input string - * @param type the type of object id * @return 0 or an error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length, git_oid_t type); -#else GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length); -#endif /** * Copy an already raw oid into a git_oid structure. @@ -167,10 +166,8 @@ GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length); * @param raw the raw input bytes to be copied. * @return 0 on success or error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw, git_oid_t type); -#else GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw); + #endif /** @@ -310,6 +307,7 @@ GIT_EXTERN(int) git_oid_strcmp(const git_oid *id, const char *str); /** * Check is an oid is all zeros. * + * @param id the object ID to check * @return 1 if all zeros, 0 otherwise. */ GIT_EXTERN(int) git_oid_is_zero(const git_oid *id); @@ -370,4 +368,5 @@ GIT_EXTERN(void) git_oid_shorten_free(git_oid_shorten *os); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/oidarray.h b/include/git2/oidarray.h index 94fc58dab..e79a55953 100644 --- a/include/git2/oidarray.h +++ b/include/git2/oidarray.h @@ -10,6 +10,13 @@ #include "common.h" #include "oid.h" +/** + * @file git2/oidarray.h + * @brief An array of object IDs + * @defgroup git_oidarray Arrays of object IDs + * @ingroup Git + * @{ + */ GIT_BEGIN_DECL /** Array of object ids */ @@ -34,4 +41,3 @@ GIT_EXTERN(void) git_oidarray_dispose(git_oidarray *array); GIT_END_DECL #endif - diff --git a/include/git2/pack.h b/include/git2/pack.h index bee72a6c0..3837e0446 100644 --- a/include/git2/pack.h +++ b/include/git2/pack.h @@ -233,7 +233,15 @@ GIT_EXTERN(size_t) git_packbuilder_object_count(git_packbuilder *pb); */ GIT_EXTERN(size_t) git_packbuilder_written(git_packbuilder *pb); -/** Packbuilder progress notification function */ +/** + * Packbuilder progress notification function. + * + * @param stage the stage of the packbuilder + * @param current the current object + * @param total the total number of objects + * @param payload the callback payload + * @return 0 on success or an error code + */ typedef int GIT_CALLBACK(git_packbuilder_progress)( int stage, uint32_t current, @@ -267,4 +275,5 @@ GIT_EXTERN(void) git_packbuilder_free(git_packbuilder *pb); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/patch.h b/include/git2/patch.h index 9cf758a3e..782482158 100644 --- a/include/git2/patch.h +++ b/include/git2/patch.h @@ -14,7 +14,7 @@ /** * @file git2/patch.h - * @brief Patch handling routines. + * @brief Patches store the textual diffs in a delta * @ingroup Git * @{ */ @@ -283,8 +283,7 @@ GIT_EXTERN(int) git_patch_to_buf( git_buf *out, git_patch *patch); +/**@}*/ GIT_END_DECL -/**@}*/ - #endif diff --git a/include/git2/pathspec.h b/include/git2/pathspec.h index acbd5cd1d..6f6918cdb 100644 --- a/include/git2/pathspec.h +++ b/include/git2/pathspec.h @@ -12,6 +12,13 @@ #include "strarray.h" #include "diff.h" +/** + * @file git2/pathspec.h + * @brief Specifiers for path matching + * @defgroup git_pathspec Specifiers for path matching + * @ingroup Git + * @{ + */ GIT_BEGIN_DECL /** @@ -276,5 +283,7 @@ GIT_EXTERN(size_t) git_pathspec_match_list_failed_entrycount( GIT_EXTERN(const char *) git_pathspec_match_list_failed_entry( const git_pathspec_match_list *m, size_t pos); +/** @} */ GIT_END_DECL + #endif diff --git a/include/git2/proxy.h b/include/git2/proxy.h index cfc0c645f..195ab75e0 100644 --- a/include/git2/proxy.h +++ b/include/git2/proxy.h @@ -12,6 +12,12 @@ #include "cert.h" #include "credential.h" +/** + * @file git2/proxy.h + * @brief TLS proxies + * @ingroup Git + * @{ + */ GIT_BEGIN_DECL /** @@ -78,7 +84,10 @@ typedef struct { void *payload; } git_proxy_options; +/** Current version for the `git_proxy_options` structure */ #define GIT_PROXY_OPTIONS_VERSION 1 + +/** Static constructor for `git_proxy_options` */ #define GIT_PROXY_OPTIONS_INIT {GIT_PROXY_OPTIONS_VERSION} /** @@ -93,6 +102,7 @@ typedef struct { */ GIT_EXTERN(int) git_proxy_options_init(git_proxy_options *opts, unsigned int version); +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/rebase.h b/include/git2/rebase.h index a53e68d9c..3fb3e5733 100644 --- a/include/git2/rebase.h +++ b/include/git2/rebase.h @@ -17,8 +17,8 @@ /** * @file git2/rebase.h - * @brief Git rebase routines - * @defgroup git_rebase Git merge routines + * @brief Rebase manipulates commits, placing them on a new parent + * @defgroup git_rebase Rebase manipulates commits, placing them on a new parent * @ingroup Git * @{ */ @@ -154,7 +154,10 @@ typedef enum { GIT_REBASE_OPERATION_EXEC } git_rebase_operation_t; +/** Current version for the `git_rebase_options` structure */ #define GIT_REBASE_OPTIONS_VERSION 1 + +/** Static constructor for `git_rebase_options` */ #define GIT_REBASE_OPTIONS_INIT \ { GIT_REBASE_OPTIONS_VERSION, 0, 0, NULL, GIT_MERGE_OPTIONS_INIT, \ GIT_CHECKOUT_OPTIONS_INIT, NULL, NULL } @@ -395,4 +398,5 @@ GIT_EXTERN(void) git_rebase_free(git_rebase *rebase); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/refdb.h b/include/git2/refdb.h index c4849abdc..536ef10da 100644 --- a/include/git2/refdb.h +++ b/include/git2/refdb.h @@ -14,8 +14,8 @@ /** * @file git2/refdb.h - * @brief Git custom refs backend functions - * @defgroup git_refdb Git custom refs backend API + * @brief A database for references (branches and tags) + * @defgroup git_refdb A database for references (branches and tags) * @ingroup Git * @{ */ diff --git a/include/git2/reflog.h b/include/git2/reflog.h index ec365c1fa..a0956c63a 100644 --- a/include/git2/reflog.h +++ b/include/git2/reflog.h @@ -13,8 +13,8 @@ /** * @file git2/reflog.h - * @brief Git reflog management routines - * @defgroup git_reflog Git reflog management routines + * @brief Reference logs store how references change + * @defgroup git_reflog Reference logs store how references change * @ingroup Git * @{ */ @@ -167,4 +167,5 @@ GIT_EXTERN(void) git_reflog_free(git_reflog *reflog); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/refs.h b/include/git2/refs.h index 06f8bb97c..d820f2a18 100644 --- a/include/git2/refs.h +++ b/include/git2/refs.h @@ -14,8 +14,8 @@ /** * @file git2/refs.h - * @brief Git reference management routines - * @defgroup git_reference Git reference management routines + * @brief References point to a commit; generally these are branches and tags + * @defgroup git_reference References point to a commit; generally these are branches and tags * @ingroup Git * @{ */ @@ -29,7 +29,7 @@ GIT_BEGIN_DECL * The name will be checked for validity. * See `git_reference_symbolic_create()` for rules about valid names. * - * @param out pointer to the looked-up reference + * @param[out] out pointer to the looked-up reference * @param repo the repository to look up the reference * @param name the long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...) * @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code. @@ -371,6 +371,7 @@ GIT_EXTERN(int) git_reference_set_target( * reflog is enabled for the repository. We only rename * the reflog if it exists. * + * @param[out] new_ref The new reference * @param ref The reference to rename * @param new_name The new name for the reference * @param force Overwrite an existing reference @@ -406,6 +407,7 @@ GIT_EXTERN(int) git_reference_delete(git_reference *ref); * This method removes the named reference from the repository without * looking at its old value. * + * @param repo The repository to remove the reference from * @param name The reference to remove * @return 0 or an error code */ @@ -518,7 +520,7 @@ GIT_EXTERN(int) git_reference_cmp( /** * Create an iterator for the repo's references * - * @param out pointer in which to store the iterator + * @param[out] out pointer in which to store the iterator * @param repo the repository * @return 0 or an error code */ @@ -543,7 +545,7 @@ GIT_EXTERN(int) git_reference_iterator_glob_new( /** * Get the next reference * - * @param out pointer in which to store the reference + * @param[out] out pointer in which to store the reference * @param iter the iterator * @return 0, GIT_ITEROVER if there are no more; or an error code */ @@ -724,7 +726,7 @@ GIT_EXTERN(int) git_reference_normalize_name( * If you pass `GIT_OBJECT_ANY` as the target type, then the object * will be peeled until a non-tag object is met. * - * @param out Pointer to the peeled git_object + * @param[out] out Pointer to the peeled git_object * @param ref The reference to be processed * @param type The type of the requested object (GIT_OBJECT_COMMIT, * GIT_OBJECT_TAG, GIT_OBJECT_TREE, GIT_OBJECT_BLOB or GIT_OBJECT_ANY). @@ -768,4 +770,5 @@ GIT_EXTERN(const char *) git_reference_shorthand(const git_reference *ref); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/refspec.h b/include/git2/refspec.h index e7087132b..16ebd1ddf 100644 --- a/include/git2/refspec.h +++ b/include/git2/refspec.h @@ -14,8 +14,8 @@ /** * @file git2/refspec.h - * @brief Git refspec attributes - * @defgroup git_refspec Git refspec attributes + * @brief Refspecs map local references to remote references + * @defgroup git_refspec Refspecs map local references to remote references * @ingroup Git * @{ */ @@ -79,7 +79,7 @@ GIT_EXTERN(int) git_refspec_force(const git_refspec *refspec); GIT_EXTERN(git_direction) git_refspec_direction(const git_refspec *spec); /** - * Check if a refspec's source descriptor matches a reference + * Check if a refspec's source descriptor matches a reference * * @param refspec the refspec * @param refname the name of the reference to check @@ -116,6 +116,7 @@ GIT_EXTERN(int) git_refspec_transform(git_buf *out, const git_refspec *spec, con */ GIT_EXTERN(int) git_refspec_rtransform(git_buf *out, const git_refspec *spec, const char *name); +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/remote.h b/include/git2/remote.h index 662fc9352..ecb7b537e 100644 --- a/include/git2/remote.h +++ b/include/git2/remote.h @@ -19,8 +19,8 @@ /** * @file git2/remote.h - * @brief Git remote management functions - * @defgroup git_remote remote management functions + * @brief Remotes are where local repositories fetch from and push to + * @defgroup git_remote Remotes are where local repositories fetch from and push to * @ingroup Git * @{ */ @@ -116,7 +116,10 @@ typedef struct git_remote_create_options { unsigned int flags; } git_remote_create_options; +/** Current version for the `git_remote_create_options` structure */ #define GIT_REMOTE_CREATE_OPTIONS_VERSION 1 + +/** Static constructor for `git_remote_create_options` */ #define GIT_REMOTE_CREATE_OPTIONS_INIT {GIT_REMOTE_CREATE_OPTIONS_VERSION} /** @@ -466,7 +469,15 @@ typedef enum git_remote_completion_t { GIT_REMOTE_COMPLETION_ERROR } git_remote_completion_t; -/** Push network progress notification function */ +/** + * Push network progress notification callback. + * + * @param current The number of objects pushed so far + * @param total The total number of objects to push + * @param bytes The number of bytes pushed + * @param payload The user-specified payload callback + * @return 0 or an error code to stop the transfer + */ typedef int GIT_CALLBACK(git_push_transfer_progress_cb)( unsigned int current, unsigned int total, @@ -502,8 +513,12 @@ typedef struct { * as commands to the destination. * @param len number of elements in `updates` * @param payload Payload provided by the caller + * @return 0 or an error code to stop the push */ -typedef int GIT_CALLBACK(git_push_negotiation)(const git_push_update **updates, size_t len, void *payload); +typedef int GIT_CALLBACK(git_push_negotiation)( + const git_push_update **updates, + size_t len, + void *payload); /** * Callback used to inform of the update status from the remote. @@ -682,7 +697,10 @@ struct git_remote_callbacks { void *data); }; +/** Current version for the `git_remote_callbacks_options` structure */ #define GIT_REMOTE_CALLBACKS_VERSION 1 + +/** Static constructor for `git_remote_callbacks_options` */ #define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION} /** @@ -809,7 +827,10 @@ typedef struct { git_strarray custom_headers; } git_fetch_options; +/** Current version for the `git_fetch_options` structure */ #define GIT_FETCH_OPTIONS_VERSION 1 + +/** Static constructor for `git_fetch_options` */ #define GIT_FETCH_OPTIONS_INIT { \ GIT_FETCH_OPTIONS_VERSION, \ GIT_REMOTE_CALLBACKS_INIT, \ @@ -877,7 +898,10 @@ typedef struct { git_strarray remote_push_options; } git_push_options; +/** Current version for the `git_push_options` structure */ #define GIT_PUSH_OPTIONS_VERSION 1 + +/** Static constructor for `git_push_options` */ #define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 1, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT } /** @@ -921,7 +945,10 @@ typedef struct { git_strarray custom_headers; } git_remote_connect_options; +/** Current version for the `git_remote_connect_options` structure */ #define GIT_REMOTE_CONNECT_OPTIONS_VERSION 1 + +/** Static constructor for `git_remote_connect_options` */ #define GIT_REMOTE_CONNECT_OPTIONS_INIT { \ GIT_REMOTE_CONNECT_OPTIONS_VERSION, \ GIT_REMOTE_CALLBACKS_INIT, \ @@ -1041,14 +1068,14 @@ GIT_EXTERN(int) git_remote_upload( * `git_remote_connect` will be used (if it was called). * * @param remote the remote to update - * @param reflog_message The message to insert into the reflogs. If - * NULL and fetching, the default is "fetch ", where is - * the name of the remote (or its url, for in-memory remotes). This - * parameter is ignored when pushing. * @param callbacks pointer to the callback structure to use or NULL * @param update_flags the git_remote_update_flags for these tips. * @param download_tags what the behaviour for downloading tags is for this fetch. This is * ignored for push. This must be the same value passed to `git_remote_download()`. + * @param reflog_message The message to insert into the reflogs. If + * NULL and fetching, the default is "fetch ", where is + * the name of the remote (or its url, for in-memory remotes). This + * parameter is ignored when pushing. * @return 0 or an error code */ GIT_EXTERN(int) git_remote_update_tips( @@ -1116,6 +1143,9 @@ GIT_EXTERN(int) git_remote_push( /** * Get the statistics structure that is filled in by the fetch operation. + * + * @param remote the remote to get statistics for + * @return the git_indexer_progress for the remote */ GIT_EXTERN(const git_indexer_progress *) git_remote_stats(git_remote *remote); @@ -1215,4 +1245,5 @@ GIT_EXTERN(int) git_remote_default_branch(git_buf *out, git_remote *remote); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/repository.h b/include/git2/repository.h index 0afda72d4..a10ea3fcb 100644 --- a/include/git2/repository.h +++ b/include/git2/repository.h @@ -15,8 +15,8 @@ /** * @file git2/repository.h - * @brief Git repository management routines - * @defgroup git_repository Git repository management routines + * @brief The repository stores revisions for a source tree + * @defgroup git_repository The repository stores revisions for a source tree * @ingroup Git * @{ */ @@ -31,7 +31,7 @@ GIT_BEGIN_DECL * The method will automatically detect if 'path' is a normal * or bare repository or fail is 'path' is neither. * - * @param out pointer to the repo which will be opened + * @param[out] out pointer to the repo which will be opened * @param path the path to the repository * @return 0 or an error code */ @@ -48,6 +48,15 @@ GIT_EXTERN(int) git_repository_open(git_repository **out, const char *path); */ GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_worktree *wt); +#ifdef GIT_EXPERIMENTAL_SHA256 + +GIT_EXTERN(int) git_repository_wrap_odb( + git_repository **out, + git_odb *odb, + git_oid_t oid_type); + +#else + /** * Create a "fake" repository to wrap an object database * @@ -57,18 +66,12 @@ GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_work * * @param out pointer to the repo * @param odb the object database to wrap - * @param oid_type the oid type of the object database * @return 0 or an error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_repository_wrap_odb( - git_repository **out, - git_odb *odb, - git_oid_t oid_type); -#else GIT_EXTERN(int) git_repository_wrap_odb( git_repository **out, git_odb *odb); + #endif /** @@ -158,7 +161,7 @@ typedef enum { /** * Find and open a repository with extended controls. * - * @param out Pointer to the repo which will be opened. This can + * @param[out] out Pointer to the repo which will be opened. This can * actually be NULL if you only want to use the error code to * see if a repo at this path could be opened. * @param path Path to open as git repository. If the flags @@ -186,7 +189,7 @@ GIT_EXTERN(int) git_repository_open_ext( * if you're e.g. hosting git repositories and need to access them * efficiently * - * @param out Pointer to the repo which will be opened. + * @param[out] out Pointer to the repo which will be opened. * @param bare_path Direct path to the bare repository * @return 0 on success, or an error code */ @@ -211,7 +214,7 @@ GIT_EXTERN(void) git_repository_free(git_repository *repo); * TODO: * - Reinit the repository * - * @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 path the path to the repository * @param is_bare if true, a Git repository without a working directory is * created at the pointed path. If false, provided path will be @@ -373,7 +376,10 @@ typedef struct { #endif } git_repository_init_options; +/** Current version for the `git_repository_init_options` structure */ #define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1 + +/** Static constructor for `git_repository_init_options` */ #define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION} /** @@ -415,7 +421,7 @@ GIT_EXTERN(int) git_repository_init_ext( * `git_reference_free()` must be called when done with it to release the * allocated memory and prevent a leak. * - * @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 * * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing @@ -636,7 +642,7 @@ GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository * The ODB must be freed once it's no longer being used by * the user. * - * @param out Pointer to store the loaded ODB + * @param[out] out Pointer to store the loaded ODB * @param repo A repository object * @return 0, or an error code */ @@ -652,7 +658,7 @@ GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo); * The refdb must be freed once it's no longer being used by * the user. * - * @param out Pointer to store the loaded refdb + * @param[out] out Pointer to store the loaded refdb * @param repo A repository object * @return 0, or an error code */ @@ -668,7 +674,7 @@ GIT_EXTERN(int) git_repository_refdb(git_refdb **out, git_repository *repo); * The index must be freed once it's no longer being used by * the user. * - * @param out Pointer to store the loaded index + * @param[out] out Pointer to store the loaded index * @param repo A repository object * @return 0, or an error code */ @@ -858,7 +864,9 @@ GIT_EXTERN(int) git_repository_set_head_detached( * * See the documentation for `git_repository_set_head_detached()`. * - * @see git_repository_set_head_detached + * @param repo Repository pointer + * @param committish annotated commit to point HEAD to + * @return 0 on success, or an error code */ GIT_EXTERN(int) git_repository_set_head_detached_from_annotated( git_repository *repo, @@ -951,8 +959,8 @@ GIT_EXTERN(int) git_repository_is_shallow(git_repository *repo); * The memory is owned by the repository and must not be freed by the * user. * - * @param name where to store the pointer to the name - * @param email where to store the pointer to the email + * @param[out] name where to store the pointer to the name + * @param[out] email where to store the pointer to the email * @param repo the repository * @return 0 or an error code */ @@ -993,4 +1001,5 @@ GIT_EXTERN(int) git_repository_commit_parents(git_commitarray *commits, git_repo /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/reset.h b/include/git2/reset.h index b2ee2ba7b..0123f7c76 100644 --- a/include/git2/reset.h +++ b/include/git2/reset.h @@ -14,7 +14,7 @@ /** * @file git2/reset.h - * @brief Git reset management routines + * @brief Reset will update the local repository to a prior state * @ingroup Git * @{ */ @@ -75,11 +75,23 @@ GIT_EXTERN(int) git_reset( * * See the documentation for `git_reset()`. * - * @see git_reset + * @param repo Repository where to perform the reset operation. + * + * @param target Annotated commit to which the Head should be moved to. + * This object must belong to the given `repo`, it will be dereferenced + * to a git_commit which oid will be used as the target of the branch. + * + * @param reset_type Kind of reset operation to perform. + * + * @param checkout_opts Optional checkout options to be used for a HARD reset. + * The checkout_strategy field will be overridden (based on reset_type). + * This parameter can be used to propagate notify and progress callbacks. + * + * @return 0 on success or an error code */ GIT_EXTERN(int) git_reset_from_annotated( git_repository *repo, - const git_annotated_commit *commit, + const git_annotated_commit *target, git_reset_t reset_type, const git_checkout_options *checkout_opts); @@ -108,4 +120,5 @@ GIT_EXTERN(int) git_reset_default( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/revert.h b/include/git2/revert.h index 331e90dff..ec51eca2d 100644 --- a/include/git2/revert.h +++ b/include/git2/revert.h @@ -13,8 +13,8 @@ /** * @file git2/revert.h - * @brief Git revert routines - * @defgroup git_revert Git revert routines + * @brief Cherry-pick the inverse of a change to "undo" its effects + * @defgroup git_revert Cherry-pick the inverse of a change to "undo" its effects * @ingroup Git * @{ */ @@ -33,8 +33,13 @@ typedef struct { git_checkout_options checkout_opts; /**< Options for the checkout */ } git_revert_options; +/** Current version for the `git_revert_options` structure */ #define GIT_REVERT_OPTIONS_VERSION 1 -#define GIT_REVERT_OPTIONS_INIT {GIT_REVERT_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT} + +/** Static constructor for `git_revert_options` */ +#define GIT_REVERT_OPTIONS_INIT { \ + GIT_REVERT_OPTIONS_VERSION, 0, \ + GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT } /** * Initialize git_revert_options structure @@ -87,5 +92,5 @@ GIT_EXTERN(int) git_revert( /** @} */ GIT_END_DECL -#endif +#endif diff --git a/include/git2/revparse.h b/include/git2/revparse.h index 51ea2dc13..c14fe3dc8 100644 --- a/include/git2/revparse.h +++ b/include/git2/revparse.h @@ -12,8 +12,8 @@ /** * @file git2/revparse.h - * @brief Git revision parsing routines - * @defgroup git_revparse Git revision parsing routines + * @brief Parse the textual revision information + * @defgroup git_revparse Parse the textual revision information * @ingroup Git * @{ */ @@ -107,7 +107,7 @@ GIT_EXTERN(int) git_revparse( git_repository *repo, const char *spec); - /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/revwalk.h b/include/git2/revwalk.h index 4aa9f5b1e..7c4ac5465 100644 --- a/include/git2/revwalk.h +++ b/include/git2/revwalk.h @@ -13,8 +13,8 @@ /** * @file git2/revwalk.h - * @brief Git revision traversal routines - * @defgroup git_revwalk Git revision traversal routines + * @brief Traverse (walk) the commit graph (revision history) + * @defgroup git_revwalk Traverse (walk) the commit graph (revision history) * @ingroup Git * @{ */ @@ -299,4 +299,5 @@ GIT_EXTERN(int) git_revwalk_add_hide_cb( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/signature.h b/include/git2/signature.h index a027d25dc..20ec24b34 100644 --- a/include/git2/signature.h +++ b/include/git2/signature.h @@ -12,9 +12,13 @@ /** * @file git2/signature.h - * @brief Git signature creation + * @brief Signatures are the actor in a repository and when they acted * @defgroup git_signature Git signature creation * @ingroup Git + * + * Signatures contain the information about the actor (committer or + * author) in a repository, and the time that they performed the + * commit, or authoring. * @{ */ GIT_BEGIN_DECL @@ -140,4 +144,5 @@ GIT_EXTERN(void) git_signature_free(git_signature *sig); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/stash.h b/include/git2/stash.h index b43ae6b24..ad28c3263 100644 --- a/include/git2/stash.h +++ b/include/git2/stash.h @@ -13,8 +13,13 @@ /** * @file git2/stash.h - * @brief Git stash management routines + * @brief Stashes stores some uncommitted state in the repository * @ingroup Git + * + * Stashes stores some uncommitted state in the repository; generally + * this allows a user to stash some changes so that they can restore + * the working directory to an unmodified state. This can allow a + * developer to work on two different changes in parallel. * @{ */ GIT_BEGIN_DECL @@ -94,7 +99,10 @@ typedef struct git_stash_save_options { git_strarray paths; } git_stash_save_options; +/** Current version for the `git_stash_save_options` structure */ #define GIT_STASH_SAVE_OPTIONS_VERSION 1 + +/** Static constructor for `git_stash_save_options` */ #define GIT_STASH_SAVE_OPTIONS_INIT { GIT_STASH_SAVE_OPTIONS_VERSION } /** @@ -165,6 +173,10 @@ typedef enum { * Stash application progress notification function. * Return 0 to continue processing, or a negative value to * abort the stash application. + * + * @param progress the progress information + * @param payload the user-specified payload to the apply function + * @return 0 on success, -1 on error */ typedef int GIT_CALLBACK(git_stash_apply_progress_cb)( git_stash_apply_progress_t progress, @@ -191,7 +203,10 @@ typedef struct git_stash_apply_options { void *progress_payload; } git_stash_apply_options; +/** Current version for the `git_stash_apply_options` structure */ #define GIT_STASH_APPLY_OPTIONS_VERSION 1 + +/** Static constructor for `git_stash_apply_options` */ #define GIT_STASH_APPLY_OPTIONS_INIT { \ GIT_STASH_APPLY_OPTIONS_VERSION, \ GIT_STASH_APPLY_DEFAULT, \ @@ -309,4 +324,5 @@ GIT_EXTERN(int) git_stash_pop( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/status.h b/include/git2/status.h index bb28e875b..e13783b67 100644 --- a/include/git2/status.h +++ b/include/git2/status.h @@ -14,7 +14,7 @@ /** * @file git2/status.h - * @brief Git file status routines + * @brief Status indicates how a user has changed the working directory and index * @defgroup git_status Git file status routines * @ingroup Git * @{ @@ -54,11 +54,10 @@ typedef enum { /** * Function pointer to receive status on individual files * - * `path` is the relative path to the file from the root of the repository. - * - * `status_flags` is a combination of `git_status_t` values that apply. - * - * `payload` is the value you passed to the foreach function as payload. + * @param path is the path to the file + * @param status_flags the `git_status_t` values for file's status + * @param payload the user-specified payload to the foreach function + * @return 0 on success, or a negative number on failure */ typedef int GIT_CALLBACK(git_status_cb)( const char *path, unsigned int status_flags, void *payload); @@ -207,6 +206,7 @@ typedef enum { GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 15) } git_status_opt_t; +/** Default `git_status_opt_t` values */ #define GIT_STATUS_OPT_DEFAULTS \ (GIT_STATUS_OPT_INCLUDE_IGNORED | \ GIT_STATUS_OPT_INCLUDE_UNTRACKED | \ @@ -261,7 +261,10 @@ typedef struct { uint16_t rename_threshold; } git_status_options; +/** Current version for the `git_status_options` structure */ #define GIT_STATUS_OPTIONS_VERSION 1 + +/** Static constructor for `git_status_options` */ #define GIT_STATUS_OPTIONS_INIT {GIT_STATUS_OPTIONS_VERSION} /** @@ -449,4 +452,5 @@ GIT_EXTERN(int) git_status_should_ignore( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/strarray.h b/include/git2/strarray.h index 03d93f8fb..dcb628a18 100644 --- a/include/git2/strarray.h +++ b/include/git2/strarray.h @@ -11,8 +11,8 @@ /** * @file git2/strarray.h - * @brief Git string array routines - * @defgroup git_strarray Git string array routines + * @brief An array of strings for the user to free + * @defgroup git_strarray An array of strings for the user to free * @ingroup Git * @{ */ @@ -40,4 +40,3 @@ GIT_EXTERN(void) git_strarray_dispose(git_strarray *array); GIT_END_DECL #endif - diff --git a/include/git2/submodule.h b/include/git2/submodule.h index 25d6687a9..911b3cee3 100644 --- a/include/git2/submodule.h +++ b/include/git2/submodule.h @@ -15,7 +15,7 @@ /** * @file git2/submodule.h - * @brief Git submodule management utilities + * @brief Submodules place another repository's contents within this one * * Submodule support in libgit2 builds a list of known submodules and keeps * it in the repository. The list is built from the .gitmodules file, the @@ -88,20 +88,27 @@ typedef enum { GIT_SUBMODULE_STATUS_WD_UNTRACKED = (1u << 13) } git_submodule_status_t; +/** Submodule source bits */ #define GIT_SUBMODULE_STATUS__IN_FLAGS 0x000Fu +/** Submodule index status */ #define GIT_SUBMODULE_STATUS__INDEX_FLAGS 0x0070u +/** Submodule working directory status */ #define GIT_SUBMODULE_STATUS__WD_FLAGS 0x3F80u +/** Whether the submodule is modified */ #define GIT_SUBMODULE_STATUS_IS_UNMODIFIED(S) \ (((S) & ~GIT_SUBMODULE_STATUS__IN_FLAGS) == 0) +/** Whether the submodule is modified (in the index) */ #define GIT_SUBMODULE_STATUS_IS_INDEX_UNMODIFIED(S) \ (((S) & GIT_SUBMODULE_STATUS__INDEX_FLAGS) == 0) +/** Whether the submodule is modified (in the working directory) */ #define GIT_SUBMODULE_STATUS_IS_WD_UNMODIFIED(S) \ (((S) & (GIT_SUBMODULE_STATUS__WD_FLAGS & \ ~GIT_SUBMODULE_STATUS_WD_UNINITIALIZED)) == 0) +/** Whether the submodule working directory is dirty */ #define GIT_SUBMODULE_STATUS_IS_WD_DIRTY(S) \ (((S) & (GIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED | \ GIT_SUBMODULE_STATUS_WD_WD_MODIFIED | \ @@ -150,7 +157,10 @@ typedef struct git_submodule_update_options { int allow_fetch; } git_submodule_update_options; +/** Current version for the `git_submodule_update_options` structure */ #define GIT_SUBMODULE_UPDATE_OPTIONS_VERSION 1 + +/** Static constructor for `git_submodule_update_options` */ #define GIT_SUBMODULE_UPDATE_OPTIONS_INIT \ { GIT_SUBMODULE_UPDATE_OPTIONS_VERSION, \ GIT_CHECKOUT_OPTIONS_INIT, \ @@ -530,7 +540,8 @@ GIT_EXTERN(int) git_submodule_set_update( * Note that at this time, libgit2 does not honor this setting and the * fetch functionality current ignores submodules. * - * @return 0 if fetchRecurseSubmodules is false, 1 if true + * @param submodule the submodule to examine + * @return the submodule recursion configuration */ GIT_EXTERN(git_submodule_recurse_t) git_submodule_fetch_recurse_submodules( git_submodule *submodule); @@ -542,7 +553,7 @@ GIT_EXTERN(git_submodule_recurse_t) git_submodule_fetch_recurse_submodules( * * @param repo the repository to affect * @param name the submodule to configure - * @param fetch_recurse_submodules Boolean value + * @param fetch_recurse_submodules the submodule recursion configuration * @return old value for fetchRecurseSubmodules */ GIT_EXTERN(int) git_submodule_set_fetch_recurse_submodules( @@ -664,4 +675,5 @@ GIT_EXTERN(int) git_submodule_location( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/alloc.h b/include/git2/sys/alloc.h index e7f85b890..67506f2b1 100644 --- a/include/git2/sys/alloc.h +++ b/include/git2/sys/alloc.h @@ -10,6 +10,17 @@ #include "git2/common.h" +/** + * @file git2/sys/alloc.h + * @brief Custom memory allocators + * @defgroup git_merge Git merge routines + * @ingroup Git + * + * Users can configure custom allocators; this is particularly + * interesting when running in constrained environments, when calling + * from another language, or during testing. + * @{ + */ GIT_BEGIN_DECL /** @@ -62,6 +73,7 @@ int git_stdalloc_init_allocator(git_allocator *allocator); */ int git_win32_crtdbg_init_allocator(git_allocator *allocator); +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/sys/commit.h b/include/git2/sys/commit.h index ba671061f..a8253c067 100644 --- a/include/git2/sys/commit.h +++ b/include/git2/sys/commit.h @@ -14,7 +14,7 @@ /** * @file git2/sys/commit.h * @brief Low-level Git commit creation - * @defgroup git_backend Git custom backend APIs + * @defgroup git_commit Low-level Git commit creation * @ingroup Git * @{ */ @@ -29,7 +29,43 @@ GIT_BEGIN_DECL * the `tree`, neither the `parents` list of `git_oid`s are checked for * validity. * - * @see git_commit_create + * @param id Pointer in which to store the OID of the newly created commit + * + * @param repo Repository where to store the commit + * + * @param update_ref If not NULL, name of the reference that + * will be updated to point to this commit. If the reference + * is not direct, it will be resolved to a direct reference. + * Use "HEAD" to update the HEAD of the current branch and + * make it point to this commit. If the reference doesn't + * exist yet, it will be created. If it does exist, the first + * parent must be the tip of this branch. + * + * @param author Signature with author and author time of commit + * + * @param committer Signature with committer and * commit time of commit + * + * @param message_encoding The encoding for the message in the + * commit, represented with a standard encoding name. + * E.g. "UTF-8". If NULL, no encoding header is written and + * UTF-8 is assumed. + * + * @param message Full message for this commit + * + * @param tree An instance of a `git_tree` object that will + * be used as the tree for the commit. This tree object must + * also be owned by the given `repo`. + * + * @param parent_count Number of parents for this commit + * + * @param parents Array of `parent_count` pointers to `git_commit` + * objects that will be used as the parents for this commit. This + * array may be NULL if `parent_count` is 0 (root commit). All the + * given commits must be owned by the `repo`. + * + * @return 0 or an error code + * The created commit will be written to the Object Database and + * the given reference will be updated to point to it */ GIT_EXTERN(int) git_commit_create_from_ids( git_oid *id, @@ -49,6 +85,10 @@ GIT_EXTERN(int) git_commit_create_from_ids( * This is invoked with the count of the number of parents processed so far * along with the user supplied payload. This should return a git_oid of * the next parent or NULL if all parents have been provided. + * + * @param idx the index of the parent + * @param payload the user-specified payload + * @return the object id of the parent, or NULL if there are no further parents */ typedef const git_oid * GIT_CALLBACK(git_commit_parent_callback)(size_t idx, void *payload); @@ -61,7 +101,40 @@ typedef const git_oid * GIT_CALLBACK(git_commit_parent_callback)(size_t idx, voi * with `parent_payload` and should return `git_oid` values or NULL to * indicate that all parents are accounted for. * - * @see git_commit_create + * @param id Pointer in which to store the OID of the newly created commit + * + * @param repo Repository where to store the commit + * + * @param update_ref If not NULL, name of the reference that + * will be updated to point to this commit. If the reference + * is not direct, it will be resolved to a direct reference. + * Use "HEAD" to update the HEAD of the current branch and + * make it point to this commit. If the reference doesn't + * exist yet, it will be created. If it does exist, the first + * parent must be the tip of this branch. + * + * @param author Signature with author and author time of commit + * + * @param committer Signature with committer and * commit time of commit + * + * @param message_encoding The encoding for the message in the + * commit, represented with a standard encoding name. + * E.g. "UTF-8". If NULL, no encoding header is written and + * UTF-8 is assumed. + * + * @param message Full message for this commit + * + * @param tree An instance of a `git_tree` object that will + * be used as the tree for the commit. This tree object must + * also be owned by the given `repo`. + * + * @param parent_cb Callback to invoke to obtain parent information + * + * @param parent_payload User-specified payload to provide to the callback + * + * @return 0 or an error code + * The created commit will be written to the Object Database and + * the given reference will be updated to point to it */ GIT_EXTERN(int) git_commit_create_from_callback( git_oid *id, @@ -77,4 +150,5 @@ GIT_EXTERN(int) git_commit_create_from_callback( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/commit_graph.h b/include/git2/sys/commit_graph.h index 06e045fcd..838efee55 100644 --- a/include/git2/sys/commit_graph.h +++ b/include/git2/sys/commit_graph.h @@ -12,8 +12,8 @@ /** * @file git2/sys/commit_graph.h - * @brief Git commit-graph - * @defgroup git_commit_graph Git commit-graph APIs + * @brief Commit graphs store information about commit relationships + * @defgroup git_commit_graph Commit graphs * @ingroup Git * @{ */ @@ -136,7 +136,10 @@ typedef struct { size_t max_commits; } git_commit_graph_writer_options; +/** Current version for the `git_commit_graph_writer_options` structure */ #define GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION 1 + +/** Static constructor for `git_commit_graph_writer_options` */ #define GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT { \ GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION \ } @@ -181,4 +184,5 @@ GIT_EXTERN(int) git_commit_graph_writer_dump( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/config.h b/include/git2/sys/config.h index a45d5f807..cc4a3991d 100644 --- a/include/git2/sys/config.h +++ b/include/git2/sys/config.h @@ -13,14 +13,19 @@ /** * @file git2/sys/config.h - * @brief Git config backend routines - * @defgroup git_backend Git custom backend APIs + * @brief Custom configuration database backends + * @defgroup git_backend Custom configuration database backends * @ingroup Git * @{ */ GIT_BEGIN_DECL +/** + * An entry in a configuration backend. This is provided so that + * backend implementors can have a mechanism to free their data. + */ typedef struct git_config_backend_entry { + /** The base configuration entry */ struct git_config_entry entry; /** @@ -93,7 +98,11 @@ struct git_config_backend { int GIT_CALLBACK(unlock)(struct git_config_backend *, int success); void GIT_CALLBACK(free)(struct git_config_backend *); }; + +/** Current version for the `git_config_backend_options` structure */ #define GIT_CONFIG_BACKEND_VERSION 1 + +/** Static constructor for `git_config_backend_options` */ #define GIT_CONFIG_BACKEND_INIT {GIT_CONFIG_BACKEND_VERSION} /** @@ -152,7 +161,10 @@ typedef struct { const char *origin_path; } git_config_backend_memory_options; +/** Current version for the `git_config_backend_memory_options` structure */ #define GIT_CONFIG_BACKEND_MEMORY_OPTIONS_VERSION 1 + +/** Static constructor for `git_config_backend_memory_options` */ #define GIT_CONFIG_BACKEND_MEMORY_OPTIONS_INIT { GIT_CONFIG_BACKEND_MEMORY_OPTIONS_VERSION } @@ -164,6 +176,7 @@ typedef struct { * @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 + * @return 0 on success or an error code */ extern int git_config_backend_from_string( git_config_backend **out, @@ -179,6 +192,7 @@ extern int git_config_backend_from_string( * @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 + * @return 0 on success or an error code */ extern int git_config_backend_from_values( git_config_backend **out, @@ -188,4 +202,5 @@ extern int git_config_backend_from_values( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/credential.h b/include/git2/sys/credential.h index bb4c9f942..0d573a323 100644 --- a/include/git2/sys/credential.h +++ b/include/git2/sys/credential.h @@ -11,9 +11,9 @@ #include "git2/credential.h" /** - * @file git2/sys/cred.h - * @brief Git credentials low-level implementation - * @defgroup git_credential Git credentials low-level implementation + * @file git2/sys/credential.h + * @brief Low-level credentials implementation + * @defgroup git_credential Low-level credentials implementation * @ingroup Git * @{ */ @@ -85,6 +85,7 @@ struct git_credential_ssh_custom { void *payload; /**< Payload passed to prompt_callback */ }; +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/sys/diff.h b/include/git2/sys/diff.h index aefd7b997..a398f5490 100644 --- a/include/git2/sys/diff.h +++ b/include/git2/sys/diff.h @@ -15,7 +15,7 @@ /** * @file git2/sys/diff.h - * @brief Low-level Git diff utilities + * @brief Low-level diff utilities * @ingroup Git * @{ */ @@ -33,6 +33,12 @@ GIT_BEGIN_DECL * must pass a `git_buf *` value as the payload to the `git_diff_print` * and/or `git_patch_print` function. The data will be appended to the * buffer (after any existing content). + * + * @param delta the delta being processed + * @param hunk the hunk being processed + * @param line the line being processed + * @param payload the payload provided by the diff generator + * @return 0 on success or an error code */ GIT_EXTERN(int) git_diff_print_callback__to_buf( const git_diff_delta *delta, @@ -53,6 +59,12 @@ GIT_EXTERN(int) git_diff_print_callback__to_buf( * value from `fopen()`) as the payload to the `git_diff_print` * and/or `git_patch_print` function. If you pass NULL, this will write * data to `stdout`. + * + * @param delta the delta being processed + * @param hunk the hunk being processed + * @param line the line being processed + * @param payload the payload provided by the diff generator + * @return 0 on success or an error code */ GIT_EXTERN(int) git_diff_print_callback__to_file_handle( const git_diff_delta *delta, @@ -70,7 +82,10 @@ typedef struct { size_t oid_calculations; /**< Number of ID calculations */ } git_diff_perfdata; +/** Current version for the `git_diff_perfdata_options` structure */ #define GIT_DIFF_PERFDATA_VERSION 1 + +/** Static constructor for `git_diff_perfdata_options` */ #define GIT_DIFF_PERFDATA_INIT {GIT_DIFF_PERFDATA_VERSION,0,0} /** @@ -85,10 +100,15 @@ GIT_EXTERN(int) git_diff_get_perfdata( /** * Get performance data for diffs from a git_status_list + * + * @param out Structure to be filled with diff performance data + * @param status Diff to read performance data from + * @return 0 for success, <0 for error */ GIT_EXTERN(int) git_status_list_get_perfdata( git_diff_perfdata *out, const git_status_list *status); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/email.h b/include/git2/sys/email.h index 5029f9a53..26e792abf 100644 --- a/include/git2/sys/email.h +++ b/include/git2/sys/email.h @@ -33,6 +33,7 @@ GIT_BEGIN_DECL * @param body optional text to include above the diffstat * @param author the person who authored this commit * @param opts email creation options + * @return 0 on success or an error code */ GIT_EXTERN(int) git_email_create_from_diff( git_buf *out, @@ -47,4 +48,5 @@ GIT_EXTERN(int) git_email_create_from_diff( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/errors.h b/include/git2/sys/errors.h index 3ae121524..44e8ecba8 100644 --- a/include/git2/sys/errors.h +++ b/include/git2/sys/errors.h @@ -10,6 +10,15 @@ #include "git2/common.h" +/** + * @file git2/sys/errors.h + * @brief Advanced error handling + * @ingroup Git + * + * Error handling for advanced consumers; those who use callbacks + * or those who create custom databases. + * @{ + */ GIT_BEGIN_DECL /** @@ -61,6 +70,7 @@ GIT_EXTERN(int) git_error_set_str(int error_class, const char *string); */ GIT_EXTERN(void) git_error_set_oom(void); +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/sys/filter.h b/include/git2/sys/filter.h index b3759416a..60466d173 100644 --- a/include/git2/sys/filter.h +++ b/include/git2/sys/filter.h @@ -11,8 +11,8 @@ /** * @file git2/sys/filter.h - * @brief Git filter backend and plugin routines - * @defgroup git_backend Git custom backend APIs + * @brief Custom filter backends and plugins + * @defgroup git_backend Custom filter backends and plugins * @ingroup Git * @{ */ @@ -26,7 +26,10 @@ GIT_BEGIN_DECL */ GIT_EXTERN(git_filter *) git_filter_lookup(const char *name); +/** The "crlf" filter */ #define GIT_FILTER_CRLF "crlf" + +/** The "ident" filter */ #define GIT_FILTER_IDENT "ident" /** @@ -53,6 +56,12 @@ GIT_EXTERN(git_filter *) git_filter_lookup(const char *name); * the filter list for you, but you can use this in combination with the * `git_filter_lookup` and `git_filter_list_push` functions to assemble * your own chains of filters. + * + * @param out the filter list + * @param repo the repository to use for configuration + * @param mode the filter mode (direction) + * @param options the options + * @return 0 on success or an error code */ GIT_EXTERN(int) git_filter_list_new( git_filter_list **out, @@ -72,6 +81,11 @@ GIT_EXTERN(int) git_filter_list_new( * filter. Using this function, you can either pass in a payload if you * know the expected payload format, or you can pass NULL. Some filters * may fail with a NULL payload. Good luck! + * + * @param fl the filter list + * @param filter the filter to push + * @param payload the payload for the filter + * @return 0 on success or an error code */ GIT_EXTERN(int) git_filter_list_push( git_filter_list *fl, git_filter *filter, void *payload); @@ -96,17 +110,26 @@ typedef struct git_filter_source git_filter_source; /** * Get the repository that the source data is coming from. + * + * @param src the filter source + * @return the repository for the filter information */ GIT_EXTERN(git_repository *) git_filter_source_repo(const git_filter_source *src); /** * Get the path that the source data is coming from. + * + * @param src the filter source + * @return the path that is being filtered */ GIT_EXTERN(const char *) git_filter_source_path(const git_filter_source *src); /** * Get the file mode of the source file * If the mode is unknown, this will return 0 + * + * @param src the filter source + * @return the file mode for the file being filtered */ GIT_EXTERN(uint16_t) git_filter_source_filemode(const git_filter_source *src); @@ -114,16 +137,25 @@ GIT_EXTERN(uint16_t) git_filter_source_filemode(const git_filter_source *src); * Get the OID of the source * If the OID is unknown (often the case with GIT_FILTER_CLEAN) then * this will return NULL. + * + * @param src the filter source + * @return the object id of the file being filtered */ GIT_EXTERN(const git_oid *) git_filter_source_id(const git_filter_source *src); /** * Get the git_filter_mode_t to be used + * + * @param src the filter source + * @return the mode (direction) of the filter */ GIT_EXTERN(git_filter_mode_t) git_filter_source_mode(const git_filter_source *src); /** * Get the combination git_filter_flag_t options to be applied + * + * @param src the filter source + * @return the flags of the filter */ GIT_EXTERN(uint32_t) git_filter_source_flags(const git_filter_source *src); @@ -137,6 +169,9 @@ GIT_EXTERN(uint32_t) git_filter_source_flags(const git_filter_source *src); * before the first use of the filter, so you can defer expensive * initialization operations (in case libgit2 is being used in a way that * doesn't need the filter). + * + * @param self the filter to initialize + * @return 0 on success, negative number on failure */ typedef int GIT_CALLBACK(git_filter_init_fn)(git_filter *self); @@ -149,6 +184,8 @@ typedef int GIT_CALLBACK(git_filter_init_fn)(git_filter *self); * This may be called even if the `initialize` callback was not made. * * Typically this function will free the `git_filter` object itself. + * + * @param self the filter to shutdown */ typedef void GIT_CALLBACK(git_filter_shutdown_fn)(git_filter *self); @@ -171,6 +208,12 @@ typedef void GIT_CALLBACK(git_filter_shutdown_fn)(git_filter *self); * allocated (not stack), so that it doesn't go away before the `stream` * callback can use it. If a filter allocates and assigns a value to the * `payload`, it will need a `cleanup` callback to free the payload. + * + * @param self the filter check + * @param payload a data for future filter functions + * @param src the filter source + * @param attr_values the attribute values + * @return 0 on success or a negative value on error */ typedef int GIT_CALLBACK(git_filter_check_fn)( git_filter *self, @@ -191,6 +234,12 @@ typedef int GIT_CALLBACK(git_filter_check_fn)( * The `payload` value will refer to any payload that was set by the * `check` callback. It may be read from or written to as needed. * + * @param self the filter check + * @param payload a data for future filter functions + * @param to the input buffer + * @param from the output buffer + * @param src the filter source + * @return 0 on success or a negative value on error * @deprecated use git_filter_stream_fn */ typedef int GIT_CALLBACK(git_filter_apply_fn)( @@ -209,6 +258,13 @@ typedef int GIT_CALLBACK(git_filter_apply_fn)( * `git_writestream` that will the original data will be written to; * 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 self the filter + * @param payload a data for future filter functions + * @param src the filter source + * @param next the output stream + * @return 0 on success or a negative value on error */ typedef int GIT_CALLBACK(git_filter_stream_fn)( git_writestream **out, @@ -225,6 +281,9 @@ typedef int GIT_CALLBACK(git_filter_stream_fn)( * `stream` callbacks allocated a `payload` to keep per-source filter * state, use this callback to free that payload and release resources * as required. + * + * @param self the filter + * @param payload a data for future filter functions */ typedef void GIT_CALLBACK(git_filter_cleanup_fn)( git_filter *self, @@ -291,7 +350,10 @@ struct git_filter { git_filter_cleanup_fn cleanup; }; +/** Current version for the `git_filter_options` structure */ #define GIT_FILTER_VERSION 1 + +/** Static constructor for `git_filter_options` */ #define GIT_FILTER_INIT {GIT_FILTER_VERSION} /** @@ -300,7 +362,7 @@ struct git_filter { * * @param filter the `git_filter` struct to initialize. * @param version Version the struct; pass `GIT_FILTER_VERSION` - * @return Zero on success; -1 on failure. + * @return 0 on success; -1 on failure. */ GIT_EXTERN(int) git_filter_init(git_filter *filter, unsigned int version); @@ -350,4 +412,5 @@ GIT_EXTERN(int) git_filter_unregister(const char *name); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/hashsig.h b/include/git2/sys/hashsig.h index 09c19aec0..0d7be535c 100644 --- a/include/git2/sys/hashsig.h +++ b/include/git2/sys/hashsig.h @@ -9,6 +9,16 @@ #include "git2/common.h" +/** + * @file git2/sys/hashsig.h + * @brief Signatures for file similarity comparison + * @defgroup git_hashsig Git merge routines + * @ingroup Git + * + * Hash signatures are used for file similary comparison; this is + * used for git's rename handling. + * @{ + */ GIT_BEGIN_DECL /** @@ -101,6 +111,7 @@ GIT_EXTERN(int) git_hashsig_compare( const git_hashsig *a, const git_hashsig *b); +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/sys/index.h b/include/git2/sys/index.h index 1f6d93f7a..b3b86a045 100644 --- a/include/git2/sys/index.h +++ b/include/git2/sys/index.h @@ -12,8 +12,8 @@ /** * @file git2/sys/index.h - * @brief Low-level Git index manipulation routines - * @defgroup git_backend Git custom backend APIs + * @brief Low-level index manipulation routines + * @defgroup git_index Low-level index manipulation routines * @ingroup Git * @{ */ @@ -67,6 +67,7 @@ GIT_EXTERN(const git_index_name_entry *) git_index_name_get_byindex( * @param ancestor the path of the file as it existed in the ancestor * @param ours the path of the file as it existed in our tree * @param theirs the path of the file as it existed in their tree + * @return 0 on success, or an error code */ GIT_EXTERN(int) git_index_name_add(git_index *index, const char *ancestor, const char *ours, const char *theirs); diff --git a/include/git2/sys/mempack.h b/include/git2/sys/mempack.h index 96bd8a7e8..f9173e1f9 100644 --- a/include/git2/sys/mempack.h +++ b/include/git2/sys/mempack.h @@ -15,8 +15,8 @@ /** * @file git2/sys/mempack.h - * @brief Custom ODB backend that permits packing objects in-memory - * @defgroup git_backend Git custom backend APIs + * @brief A custom object database backend for storing objects in-memory + * @defgroup git_mempack A custom object database backend for storing objects in-memory * @ingroup Git * @{ */ @@ -60,6 +60,7 @@ GIT_EXTERN(int) git_mempack_new(git_odb_backend **out); * * @param backend The mempack backend * @param pb The packbuilder to use to write the packfile + * @return 0 on success or an error code */ GIT_EXTERN(int) git_mempack_write_thin_pack(git_odb_backend *backend, git_packbuilder *pb); @@ -101,6 +102,7 @@ GIT_EXTERN(int) git_mempack_dump(git_buf *pack, git_repository *repo, git_odb_ba */ GIT_EXTERN(int) git_mempack_reset(git_odb_backend *backend); +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/sys/merge.h b/include/git2/sys/merge.h index ef4bc5aca..a9f522054 100644 --- a/include/git2/sys/merge.h +++ b/include/git2/sys/merge.h @@ -14,13 +14,18 @@ /** * @file git2/sys/merge.h - * @brief Git merge driver backend and plugin routines - * @defgroup git_merge Git merge driver APIs + * @brief Custom merge drivers + * @defgroup git_merge Custom merge drivers * @ingroup Git * @{ */ GIT_BEGIN_DECL +/** + * A "merge driver" is a mechanism that can be configured to handle + * conflict resolution for files changed in both the "ours" and "theirs" + * side of a merge. + */ typedef struct git_merge_driver git_merge_driver; /** @@ -31,8 +36,11 @@ typedef struct git_merge_driver git_merge_driver; */ GIT_EXTERN(git_merge_driver *) git_merge_driver_lookup(const char *name); +/** The "text" merge driver */ #define GIT_MERGE_DRIVER_TEXT "text" +/** The "binary" merge driver */ #define GIT_MERGE_DRIVER_BINARY "binary" +/** The "union" merge driver */ #define GIT_MERGE_DRIVER_UNION "union" /** @@ -40,23 +48,48 @@ GIT_EXTERN(git_merge_driver *) git_merge_driver_lookup(const char *name); */ typedef struct git_merge_driver_source git_merge_driver_source; -/** Get the repository that the source data is coming from. */ +/** + * Get the repository that the source data is coming from. + * + * @param src the merge driver source + * @return the repository + */ GIT_EXTERN(git_repository *) git_merge_driver_source_repo( const git_merge_driver_source *src); -/** Gets the ancestor of the file to merge. */ +/** + * Gets the ancestor of the file to merge. + * + * @param src the merge driver source + * @return the ancestor or NULL if there was no ancestor + */ GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ancestor( const git_merge_driver_source *src); -/** Gets the ours side of the file to merge. */ +/** + * Gets the ours side of the file to merge. + * + * @param src the merge driver source + * @return the ours side or NULL if there was no ours side + */ GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ours( const git_merge_driver_source *src); -/** Gets the theirs side of the file to merge. */ +/** + * Gets the theirs side of the file to merge. + * + * @param src the merge driver source + * @return the theirs side or NULL if there was no theirs side + */ GIT_EXTERN(const git_index_entry *) git_merge_driver_source_theirs( const git_merge_driver_source *src); -/** Gets the merge file options that the merge was invoked with */ +/** + * Gets the merge file options that the merge was invoked with. + * + * @param src the merge driver source + * @return the options + */ GIT_EXTERN(const git_merge_file_options *) git_merge_driver_source_file_options( const git_merge_driver_source *src); @@ -72,6 +105,9 @@ GIT_EXTERN(const git_merge_file_options *) git_merge_driver_source_file_options( * right before the first use of the driver, so you can defer expensive * initialization operations (in case libgit2 is being used in a way that * doesn't need the merge driver). + * + * @param self the merge driver to initialize + * @return 0 on success, or a negative number on failure */ typedef int GIT_CALLBACK(git_merge_driver_init_fn)(git_merge_driver *self); @@ -84,6 +120,8 @@ typedef int GIT_CALLBACK(git_merge_driver_init_fn)(git_merge_driver *self); * This may be called even if the `initialize` callback was not made. * * Typically this function will free the `git_merge_driver` object itself. + * + * @param self the merge driver to shutdown */ typedef void GIT_CALLBACK(git_merge_driver_shutdown_fn)(git_merge_driver *self); @@ -104,6 +142,14 @@ typedef void GIT_CALLBACK(git_merge_driver_shutdown_fn)(git_merge_driver *self); * specified by the file's attributes. * * The `src` contains the data about the file to be merged. + * + * @param self the merge driver + * @param path_out the resolved path + * @param mode_out the resolved mode + * @param merged_out the merged output contents + * @param filter_name the filter that was invoked + * @param src the data about the unmerged file + * @return 0 on success, or an error code */ typedef int GIT_CALLBACK(git_merge_driver_apply_fn)( git_merge_driver *self, @@ -139,6 +185,7 @@ struct git_merge_driver { git_merge_driver_apply_fn apply; }; +/** The version for the `git_merge_driver` */ #define GIT_MERGE_DRIVER_VERSION 1 /** @@ -179,4 +226,5 @@ GIT_EXTERN(int) git_merge_driver_unregister(const char *name); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/midx.h b/include/git2/sys/midx.h index 3a87484d2..2bf0d01eb 100644 --- a/include/git2/sys/midx.h +++ b/include/git2/sys/midx.h @@ -11,9 +11,9 @@ #include "git2/types.h" /** - * @file git2/midx.h - * @brief Git multi-pack-index routines - * @defgroup git_midx Git multi-pack-index routines + * @file git2/sys/midx.h + * @brief Incremental multi-pack indexes + * @defgroup git_midx Incremental multi-pack indexes * @ingroup Git * @{ */ @@ -75,4 +75,5 @@ GIT_EXTERN(int) git_midx_writer_dump( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/odb_backend.h b/include/git2/sys/odb_backend.h index c42abd370..53d8d060e 100644 --- a/include/git2/sys/odb_backend.h +++ b/include/git2/sys/odb_backend.h @@ -13,9 +13,9 @@ #include "git2/odb.h" /** - * @file git2/sys/backend.h - * @brief Git custom backend implementors functions - * @defgroup git_backend Git custom backend APIs + * @file git2/sys/odb_backend.h + * @brief Object database backends for custom object storage + * @defgroup git_backend Object database backends for custom object storage * @ingroup Git * @{ */ @@ -106,7 +106,10 @@ struct git_odb_backend { void GIT_CALLBACK(free)(git_odb_backend *); }; +/** Current version for the `git_odb_backend_options` structure */ #define GIT_ODB_BACKEND_VERSION 1 + +/** Static constructor for `git_odb_backend_options` */ #define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION} /** @@ -167,6 +170,7 @@ GIT_EXTERN(void *) git_odb_backend_malloc(git_odb_backend *backend, size_t len); #endif +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/sys/openssl.h b/include/git2/sys/openssl.h index b41c55c6d..8b74a98cd 100644 --- a/include/git2/sys/openssl.h +++ b/include/git2/sys/openssl.h @@ -9,6 +9,12 @@ #include "git2/common.h" +/** + * @file git2/sys/openssl.h + * @brief Custom OpenSSL functionality + * @defgroup git_openssl Custom OpenSSL functionality + * @{ + */ GIT_BEGIN_DECL /** @@ -33,6 +39,7 @@ GIT_BEGIN_DECL */ GIT_EXTERN(int) git_openssl_set_locking(void); +/** @} */ GIT_END_DECL -#endif +#endif diff --git a/include/git2/sys/path.h b/include/git2/sys/path.h index 2a0c7e00d..2963bca3f 100644 --- a/include/git2/sys/path.h +++ b/include/git2/sys/path.h @@ -10,6 +10,16 @@ #include "git2/common.h" +/** + * @file git2/sys/path.h + * @brief Custom path handling + * @defgroup git_path Custom path handling + * @ingroup Git + * + * Merge will take two commits and attempt to produce a commit that + * includes the changes that were made in both branches. + * @{ + */ GIT_BEGIN_DECL /** @@ -59,6 +69,7 @@ typedef enum { */ GIT_EXTERN(int) git_path_is_gitfile(const char *path, size_t pathlen, git_path_gitfile gitfile, git_path_fs fs); +/** @} */ GIT_END_DECL -#endif /* INCLUDE_sys_git_path */ +#endif diff --git a/include/git2/sys/refdb_backend.h b/include/git2/sys/refdb_backend.h index c31e26d95..e88505b5e 100644 --- a/include/git2/sys/refdb_backend.h +++ b/include/git2/sys/refdb_backend.h @@ -12,9 +12,9 @@ #include "git2/oid.h" /** - * @file git2/refdb_backend.h - * @brief Git custom refs backend functions - * @defgroup git_refdb_backend Git custom refs backend API + * @file git2/sys/refdb_backend.h + * @brief Custom reference database backends for refs storage + * @defgroup git_refdb_backend Custom reference database backends for refs storage * @ingroup Git * @{ */ @@ -312,7 +312,10 @@ struct git_refdb_backend { const git_reference *ref, const git_signature *sig, const char *message); }; +/** Current version for the `git_refdb_backend_options` structure */ #define GIT_REFDB_BACKEND_VERSION 1 + +/** Static constructor for `git_refdb_backend_options` */ #define GIT_REFDB_BACKEND_INIT {GIT_REFDB_BACKEND_VERSION} /** @@ -356,6 +359,7 @@ GIT_EXTERN(int) git_refdb_set_backend( git_refdb *refdb, git_refdb_backend *backend); +/** @} */ GIT_END_DECL #endif diff --git a/include/git2/sys/refs.h b/include/git2/sys/refs.h index d2ce2e0b9..e434e67c3 100644 --- a/include/git2/sys/refs.h +++ b/include/git2/sys/refs.h @@ -13,8 +13,8 @@ /** * @file git2/sys/refs.h - * @brief Low-level Git ref creation - * @defgroup git_backend Git custom backend APIs + * @brief Low-level git reference creation + * @defgroup git_backend Low-level git reference creation * @ingroup Git * @{ */ @@ -46,4 +46,5 @@ GIT_EXTERN(git_reference *) git_reference__alloc_symbolic( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/remote.h b/include/git2/sys/remote.h index 58950e1ec..476965daa 100644 --- a/include/git2/sys/remote.h +++ b/include/git2/sys/remote.h @@ -13,7 +13,7 @@ /** * @file git2/sys/remote.h * @brief Low-level remote functionality for custom transports - * @defgroup git_remote Low-level remote functionality + * @defgroup git_remote Low-level remote functionality for custom transports * @ingroup Git * @{ */ @@ -49,4 +49,5 @@ GIT_EXTERN(void) git_remote_connect_options_dispose( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/repository.h b/include/git2/sys/repository.h index 080a404c4..eb0a33a92 100644 --- a/include/git2/sys/repository.h +++ b/include/git2/sys/repository.h @@ -13,13 +13,25 @@ /** * @file git2/sys/repository.h - * @brief Git repository custom implementation routines - * @defgroup git_backend Git custom backend APIs + * @brief Custom repository handling + * @defgroup git_repository Custom repository handling * @ingroup Git * @{ */ GIT_BEGIN_DECL +#ifdef GIT_EXPERIMENTAL_SHA256 + +/** + * Create a new repository with no backends. + * + * @param[out] out The blank repository + * @param oid_type the object ID type for this repository + * @return 0 on success, or an error code + */ +GIT_EXTERN(int) git_repository_new(git_repository **out, git_oid_t oid_type); +#else + /** * Create a new repository with neither backends nor config object * @@ -30,13 +42,11 @@ GIT_BEGIN_DECL * can fail to function properly: locations under $GIT_DIR, $GIT_COMMON_DIR, * or $GIT_INFO_DIR are impacted. * - * @param out The blank repository + * @param[out] out The blank repository * @return 0 on success, or an error code */ -#ifdef GIT_EXPERIMENTAL_SHA256 -GIT_EXTERN(int) git_repository_new(git_repository **out, git_oid_t oid_type); -#else GIT_EXTERN(int) git_repository_new(git_repository **out); + #endif /** @@ -161,6 +171,7 @@ GIT_EXTERN(int) git_repository_set_bare(git_repository *repo); * and caches them so that subsequent calls to `git_submodule_lookup` are O(1). * * @param repo the repository whose submodules will be cached. + * @return 0 on success, or an error code */ GIT_EXTERN(int) git_repository_submodule_cache_all( git_repository *repo); @@ -176,10 +187,12 @@ GIT_EXTERN(int) git_repository_submodule_cache_all( * of these has changed, the cache might become invalid. * * @param repo the repository whose submodule cache will be cleared + * @return 0 on success, or an error code */ GIT_EXTERN(int) git_repository_submodule_cache_clear( git_repository *repo); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/sys/stream.h b/include/git2/sys/stream.h index 3277088c9..eabff6864 100644 --- a/include/git2/sys/stream.h +++ b/include/git2/sys/stream.h @@ -11,8 +11,16 @@ #include "git2/types.h" #include "git2/proxy.h" +/** + * @file git2/sys/stream.h + * @brief Streaming file I/O functionality + * @defgroup git_stream Streaming file I/O functionality + * @ingroup Git + * @{ + */ GIT_BEGIN_DECL +/** Current version for the `git_stream` structures */ #define GIT_STREAM_VERSION 1 /** @@ -147,6 +155,7 @@ GIT_EXTERN(int) git_stream_register_tls(git_stream_cb ctor); #endif +/**@}*/ GIT_END_DECL #endif diff --git a/include/git2/sys/transport.h b/include/git2/sys/transport.h index 370ca45d5..ad6765c62 100644 --- a/include/git2/sys/transport.h +++ b/include/git2/sys/transport.h @@ -18,14 +18,20 @@ /** * @file git2/sys/transport.h - * @brief Git custom transport registration interfaces and functions - * @defgroup git_transport Git custom transport registration + * @brief Custom transport registration interfaces and functions + * @defgroup git_transport Custom transport registration * @ingroup Git + * + * Callers can override the default HTTPS or SSH implementation by + * specifying a custom transport. * @{ */ GIT_BEGIN_DECL +/** + * The negotiation state during a fetch smart transport negotiation. + */ typedef struct { const git_remote_head * const *refs; size_t refs_len; @@ -146,7 +152,10 @@ struct git_transport { void GIT_CALLBACK(free)(git_transport *transport); }; +/** Current version for the `git_transport` structure */ #define GIT_TRANSPORT_VERSION 1 + +/** Static constructor for `git_transport` */ #define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION} /** @@ -299,6 +308,7 @@ GIT_EXTERN(int) git_transport_smart_credentials(git_credential **out, git_transp * * @param out options struct to fill * @param transport the transport to extract the data from. + * @return 0 on success, or an error code */ GIT_EXTERN(int) git_transport_remote_connect_options( git_remote_connect_options *out, @@ -386,7 +396,14 @@ struct git_smart_subtransport { void GIT_CALLBACK(free)(git_smart_subtransport *transport); }; -/** A function which creates a new subtransport for the smart transport */ +/** + * A function that creates a new subtransport for the smart transport + * + * @param out the smart subtransport + * @param owner the transport owner + * @param param the input parameter + * @return 0 on success, or an error code + */ typedef int GIT_CALLBACK(git_smart_subtransport_cb)( git_smart_subtransport **out, git_transport *owner, @@ -429,6 +446,7 @@ typedef struct git_smart_subtransport_definition { * * @param 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 */ GIT_EXTERN(int) git_smart_subtransport_http( @@ -441,6 +459,7 @@ GIT_EXTERN(int) git_smart_subtransport_http( * * @param 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 */ GIT_EXTERN(int) git_smart_subtransport_git( @@ -453,6 +472,7 @@ GIT_EXTERN(int) git_smart_subtransport_git( * * @param 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 */ GIT_EXTERN(int) git_smart_subtransport_ssh( @@ -462,4 +482,5 @@ GIT_EXTERN(int) git_smart_subtransport_ssh( /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/tag.h b/include/git2/tag.h index 983053655..3b0c12ebc 100644 --- a/include/git2/tag.h +++ b/include/git2/tag.h @@ -15,7 +15,7 @@ /** * @file git2/tag.h - * @brief Git tag parsing routines + * @brief A (nearly) immutable pointer to a commit; useful for versioning * @defgroup git_tag Git tag management * @ingroup Git * @{ @@ -335,6 +335,7 @@ typedef int GIT_CALLBACK(git_tag_foreach_cb)(const char *name, git_oid *oid, voi * @param repo Repository * @param callback Callback function * @param payload Pointer to callback data (optional) + * @return 0 on success or an error code */ GIT_EXTERN(int) git_tag_foreach( git_repository *repo, @@ -380,4 +381,5 @@ GIT_EXTERN(int) git_tag_name_is_valid(int *valid, const char *name); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/trace.h b/include/git2/trace.h index 8cee3a94e..62cb87c01 100644 --- a/include/git2/trace.h +++ b/include/git2/trace.h @@ -12,8 +12,8 @@ /** * @file git2/trace.h - * @brief Git tracing configuration routines - * @defgroup git_trace Git tracing configuration routines + * @brief Tracing functionality to introspect libgit2 in your application + * @defgroup git_trace Tracing functionality to introspect libgit2 in your application * @ingroup Git * @{ */ @@ -48,8 +48,13 @@ typedef enum { /** * An instance for a tracing function + * + * @param level the trace level + * @param msg the trace message */ -typedef void GIT_CALLBACK(git_trace_cb)(git_trace_level_t level, const char *msg); +typedef void GIT_CALLBACK(git_trace_cb)( + git_trace_level_t level, + const char *msg); /** * Sets the system tracing configuration to the specified level with the @@ -64,4 +69,5 @@ GIT_EXTERN(int) git_trace_set(git_trace_level_t level, git_trace_cb cb); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/transaction.h b/include/git2/transaction.h index 4938570b5..212d32919 100644 --- a/include/git2/transaction.h +++ b/include/git2/transaction.h @@ -12,8 +12,8 @@ /** * @file git2/transaction.h - * @brief Git transactional reference routines - * @defgroup git_transaction Git transactional reference routines + * @brief Transactional reference handling + * @defgroup git_transaction Transactional reference handling * @ingroup Git * @{ */ @@ -118,4 +118,5 @@ GIT_EXTERN(void) git_transaction_free(git_transaction *tx); /** @} */ GIT_END_DECL + #endif diff --git a/include/git2/transport.h b/include/git2/transport.h index 5a27de9a8..04a7390b1 100644 --- a/include/git2/transport.h +++ b/include/git2/transport.h @@ -15,8 +15,8 @@ /** * @file git2/transport.h - * @brief Git transport interfaces and functions - * @defgroup git_transport interfaces and functions + * @brief Transports are the low-level mechanism to connect to a remote server + * @defgroup git_transport Transports are the low-level mechanism to connect to a remote server * @ingroup Git * @{ */ @@ -30,10 +30,18 @@ GIT_BEGIN_DECL * @param str The message from the transport * @param len The length of the message * @param payload Payload provided by the caller + * @return 0 on success or an error code */ typedef int GIT_CALLBACK(git_transport_message_cb)(const char *str, int len, void *payload); -/** Signature of a function which creates a transport */ +/** + * Signature of a function which creates a transport. + * + * @param 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); /** @} */ diff --git a/include/git2/tree.h b/include/git2/tree.h index ce0a60907..b8e2de217 100644 --- a/include/git2/tree.h +++ b/include/git2/tree.h @@ -14,8 +14,8 @@ /** * @file git2/tree.h - * @brief Git tree parsing, loading routines - * @defgroup git_tree Git tree parsing, loading routines + * @brief Trees are collections of files and folders to make up the repository hierarchy + * @defgroup git_tree Trees are collections of files and folders to make up the repository hierarchy * @ingroup Git * @{ */ @@ -24,7 +24,7 @@ GIT_BEGIN_DECL /** * Lookup a tree object from the repository. * - * @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. * @return 0 or an error code @@ -345,6 +345,10 @@ GIT_EXTERN(int) git_treebuilder_remove( * The return value is treated as a boolean, with zero indicating that the * entry should be left alone and any non-zero value meaning that the * entry should be removed from the treebuilder list (i.e. filtered out). + * + * @param entry the tree entry for the callback to examine + * @param payload the payload from the caller + * @return 0 to do nothing, non-zero to remove the entry */ typedef int GIT_CALLBACK(git_treebuilder_filter_cb)( const git_tree_entry *entry, void *payload); @@ -379,7 +383,14 @@ GIT_EXTERN(int) git_treebuilder_filter( GIT_EXTERN(int) git_treebuilder_write( git_oid *id, git_treebuilder *bld); -/** Callback for the tree traversal method */ +/** + * Callback for the tree traversal method. + * + * @param root the current (relative) root to the entry + * @param entry the tree entry + * @param payload the caller-provided callback payload + * @return a positive value to skip the entry, a negative value to stop the walk + */ typedef int GIT_CALLBACK(git_treewalk_cb)( const char *root, const git_tree_entry *entry, void *payload); @@ -470,6 +481,6 @@ typedef struct { GIT_EXTERN(int) git_tree_create_updated(git_oid *out, git_repository *repo, git_tree *baseline, size_t nupdates, const git_tree_update *updates); /** @} */ - GIT_END_DECL + #endif diff --git a/include/git2/types.h b/include/git2/types.h index d4b033dc7..a4afd18c3 100644 --- a/include/git2/types.h +++ b/include/git2/types.h @@ -81,13 +81,18 @@ typedef enum { GIT_OBJECT_REF_DELTA = 7 /**< A delta, base is given by object id. */ } git_object_t; -/** An open object database handle. */ +/** + * An object database stores the objects (commit, trees, blobs, tags, + * etc) for a repository. + */ typedef struct git_odb git_odb; /** A custom backend in an ODB */ typedef struct git_odb_backend git_odb_backend; -/** An object read from the ODB */ +/** + * A "raw" object read from the object database. + */ typedef struct git_odb_object git_odb_object; /** A stream to read/write from the ODB */ @@ -194,7 +199,18 @@ typedef struct git_reference_iterator git_reference_iterator; /** Transactional interface to references */ typedef struct git_transaction git_transaction; -/** Annotated commits, the input to merge and rebase. */ +/** + * Annotated commits are commits with additional metadata about how the + * commit was resolved, which can be used for maintaining the user's + * "intent" through commands like merge and rebase. + * + * For example, if a user wants to conceptually "merge `HEAD`", then the + * commit portion of an annotated commit will point to the `HEAD` commit, + * but the _annotation_ will denote the ref `HEAD`. This allows git to + * perform the internal bookkeeping so that the system knows both the + * content of what is being merged but also how the content was looked up + * so that it can be recorded in the reflog appropriately. + */ typedef struct git_annotated_commit git_annotated_commit; /** Representation of a status collection */ diff --git a/include/git2/version.h b/include/git2/version.h index 8cde510d6..d512bbb06 100644 --- a/include/git2/version.h +++ b/include/git2/version.h @@ -7,6 +7,14 @@ #ifndef INCLUDE_git_version_h__ #define INCLUDE_git_version_h__ +/** + * @file git2/version.h + * @brief The version of libgit2 + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + /** * The version string for libgit2. This string follows semantic * versioning (v2) guidelines. @@ -61,4 +69,7 @@ #define LIBGIT2_VERSION_CHECK(major, minor, revision) \ (LIBGIT2_VERSION_NUMBER >= ((major)*1000000)+((minor)*10000)+((revision)*100)) +/** @} */ +GIT_END_DECL + #endif diff --git a/include/git2/worktree.h b/include/git2/worktree.h index a6e5d17c4..fd3751753 100644 --- a/include/git2/worktree.h +++ b/include/git2/worktree.h @@ -14,9 +14,9 @@ #include "checkout.h" /** - * @file git2/worktrees.h - * @brief Git worktree related functions - * @defgroup git_commit Git worktree related functions + * @file git2/worktree.h + * @brief Additional working directories for a repository + * @defgroup git_commit Additional working directories for a repository * @ingroup Git * @{ */ @@ -96,7 +96,10 @@ typedef struct git_worktree_add_options { git_checkout_options checkout_options; } git_worktree_add_options; +/** Current version for the `git_worktree_add_options` structure */ #define GIT_WORKTREE_ADD_OPTIONS_VERSION 1 + +/** Static constructor for `git_worktree_add_options` */ #define GIT_WORKTREE_ADD_OPTIONS_INIT { GIT_WORKTREE_ADD_OPTIONS_VERSION, \ 0, 0, NULL, GIT_CHECKOUT_OPTIONS_INIT } @@ -211,7 +214,10 @@ typedef struct git_worktree_prune_options { uint32_t flags; } git_worktree_prune_options; +/** Current version for the `git_worktree_prune_options` structure */ #define GIT_WORKTREE_PRUNE_OPTIONS_VERSION 1 + +/** Static constructor for `git_worktree_prune_options` */ #define GIT_WORKTREE_PRUNE_OPTIONS_INIT {GIT_WORKTREE_PRUNE_OPTIONS_VERSION,0} /** @@ -268,4 +274,5 @@ GIT_EXTERN(int) git_worktree_prune(git_worktree *wt, /** @} */ GIT_END_DECL + #endif