Unverified Commit b6625a3b by Patrick Steinhardt Committed by GitHub

Merge pull request #5128 from tiennou/fix/docs

More documentation
parents 3d22394a 33448b45
......@@ -62,10 +62,15 @@ typedef int GIT_CALLBACK(git_apply_hunk_cb)(
* @see git_apply_to_tree, git_apply
*/
typedef struct {
unsigned int version;
unsigned int version; /**< The version */
/** When applying a patch, callback that will be made per delta (file). */
git_apply_delta_cb delta_cb;
/** 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. */
void *payload;
} git_apply_options;
......
......@@ -32,26 +32,32 @@ GIT_BEGIN_DECL
* a block of memory they hold. In this case, libgit2 will not resize or
* free the memory, but will read from it as needed.
*
* A `git_buf` is a public structure with three fields:
*
* - `ptr` points to the start of the allocated memory. If it is NULL,
* then the `git_buf` is considered empty and libgit2 will feel free
* to overwrite it with new data.
*
* - `size` holds the size (in bytes) of the data that is actually used.
*
* - `asize` holds the known total amount of allocated memory if the `ptr`
* was allocated by libgit2. It may be larger than `size`. If `ptr`
* was not allocated by libgit2 and should not be resized and/or freed,
* then `asize` will be set to zero.
*
* Some APIs may occasionally do something slightly unusual with a buffer,
* such as setting `ptr` to a value that was passed in by the user. In
* those cases, the behavior will be clearly documented by the API.
*/
typedef struct {
/**
* The buffer contents.
*
* `ptr` points to the start of the allocated memory. If it is NULL,
* then the `git_buf` is considered empty and libgit2 will feel free
* to overwrite it with new data.
*/
char *ptr;
size_t asize, size;
/**
* `asize` holds the known total amount of allocated memory if the `ptr`
* was allocated by libgit2. It may be larger than `size`. If `ptr`
* was not allocated by libgit2 and should not be resized and/or freed,
* then `asize` will be set to zero.
*/
size_t asize;
/**
* `size` holds the size (in bytes) of the data that is actually used.
*/
size_t size;
} git_buf;
/**
......
......@@ -261,7 +261,7 @@ typedef void GIT_CALLBACK(git_checkout_perfdata_cb)(
*
*/
typedef struct git_checkout_options {
unsigned int version;
unsigned int version; /**< The version */
unsigned int checkout_strategy; /**< default will be a safe checkout */
......@@ -271,29 +271,46 @@ typedef struct git_checkout_options {
int file_open_flags; /**< default is O_CREAT | O_TRUNC | O_WRONLY */
unsigned int notify_flags; /**< see `git_checkout_notify_t` above */
/**
* Optional callback to get notifications on specific file states.
* @see git_checkout_notify_t
*/
git_checkout_notify_cb notify_cb;
/** Payload passed to notify_cb */
void *notify_payload;
/** Optional callback to notify the consumer of checkout progress. */
git_checkout_progress_cb progress_cb;
/** Payload passed to progress_cb */
void *progress_payload;
/** When not zeroed out, array of fnmatch patterns specifying which
* paths should be taken into account, otherwise all files. Use
* GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH to treat as simple list.
/**
* A list of wildmatch patterns or paths.
*
* By default, all paths are processed. If you pass an array of wildmatch
* patterns, those will be used to filter which paths should be taken into
* account.
*
* Use GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH to treat as a simple list.
*/
git_strarray paths;
/** The expected content of the working directory; defaults to HEAD.
* If the working directory does not match this baseline information,
* that will produce a checkout conflict.
/**
* The expected content of the working directory; defaults to HEAD.
*
* If the working directory does not match this baseline information,
* that will produce a checkout conflict.
*/
git_tree *baseline;
/** Like `baseline` above, though expressed as an index. This
* option overrides `baseline`.
/**
* Like `baseline` above, though expressed as an index. This
* option overrides `baseline`.
*/
git_index *baseline_index; /**< expected content of workdir, expressed as an index. */
git_index *baseline_index;
const char *target_directory; /**< alternative checkout path to workdir */
......@@ -303,6 +320,8 @@ typedef struct git_checkout_options {
/** Optional callback to notify the consumer of performance data. */
git_checkout_perfdata_cb perfdata_cb;
/** Payload passed to perfdata_cb */
void *perfdata_payload;
} git_checkout_options;
......
......@@ -495,7 +495,8 @@ typedef int GIT_CALLBACK(git_url_resolve_cb)(git_buf *url_resolved, const char *
* about the progress of the network operations.
*/
struct git_remote_callbacks {
unsigned int version;
unsigned int version; /**< The version */
/**
* Textual progress from the remote. Text send over the
* progress side-band will be passed to this function (this is
......
......@@ -163,27 +163,36 @@ typedef enum {
/**
* Options to control how `git_status_foreach_ext()` will issue callbacks.
*
* This structure is set so that zeroing it out will give you relatively
* sane defaults.
* Initialize with `GIT_STATUS_OPTIONS_INIT`. Alternatively, you can
* use `git_status_options_init`.
*
* The `show` value is one of the `git_status_show_t` constants that
* control which files to scan and in what order.
*
* The `flags` value is an OR'ed combination of the `git_status_opt_t`
* values above.
*
* The `pathspec` is an array of path patterns to match (using
* fnmatch-style matching), or just an array of paths to match exactly if
* `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags.
*
* The `baseline` is the tree to be used for comparison to the working directory
* and index; defaults to HEAD.
*/
typedef struct {
unsigned int version;
unsigned int version; /**< The version */
/**
* The `show` value is one of the `git_status_show_t` constants that
* control which files to scan and in what order.
*/
git_status_show_t show;
/**
* The `flags` value is an OR'ed combination of the `git_status_opt_t`
* values above.
*/
unsigned int flags;
/**
* The `pathspec` is an array of path patterns to match (using
* fnmatch-style matching), or just an array of paths to match exactly if
* `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags.
*/
git_strarray pathspec;
/**
* The `baseline` is the tree to be used for comparison to the working directory
* and index; defaults to HEAD.
*/
git_tree *baseline;
} git_status_options;
......
......@@ -21,51 +21,51 @@ GIT_BEGIN_DECL
* that all fields need to be set to a proper function.
*/
typedef struct {
/* Allocate `n` bytes of memory */
/** Allocate `n` bytes of memory */
void * GIT_CALLBACK(gmalloc)(size_t n, const char *file, int line);
/*
/**
* Allocate memory for an array of `nelem` elements, where each element
* has a size of `elsize`. Returned memory shall be initialized to
* all-zeroes
*/
void * GIT_CALLBACK(gcalloc)(size_t nelem, size_t elsize, const char *file, int line);
/* Allocate memory for the string `str` and duplicate its contents. */
/** Allocate memory for the string `str` and duplicate its contents. */
char * GIT_CALLBACK(gstrdup)(const char *str, const char *file, int line);
/*
/**
* Equivalent to the `gstrdup` function, but only duplicating at most
* `n + 1` bytes
*/
char * GIT_CALLBACK(gstrndup)(const char *str, size_t n, const char *file, int line);
/*
/**
* Equivalent to `gstrndup`, but will always duplicate exactly `n` bytes
* of `str`. Thus, out of bounds reads at `str` may happen.
*/
char * GIT_CALLBACK(gsubstrdup)(const char *str, size_t n, const char *file, int line);
/*
/**
* This function shall deallocate the old object `ptr` and return a
* pointer to a new object that has the size specified by `size`. In
* case `ptr` is `NULL`, a new array shall be allocated.
*/
void * GIT_CALLBACK(grealloc)(void *ptr, size_t size, const char *file, int line);
/*
/**
* This function shall be equivalent to `grealloc`, but allocating
* `neleme * elsize` bytes.
*/
void * GIT_CALLBACK(greallocarray)(void *ptr, size_t nelem, size_t elsize, const char *file, int line);
/*
/**
* This function shall allocate a new array of `nelem` elements, where
* each element has a size of `elsize` bytes.
*/
void * GIT_CALLBACK(gmallocarray)(size_t nelem, size_t elsize, const char *file, int line);
/*
/**
* This function shall free the memory pointed to by `ptr`. In case
* `ptr` is `NULL`, this shall be a no-op.
*/
......
......@@ -37,7 +37,7 @@ typedef enum {
* Hostkey information taken from libssh2
*/
typedef struct {
git_cert parent;
git_cert parent; /**< The parent cert */
/**
* A hostkey type from libssh2, either
......@@ -62,11 +62,13 @@ typedef struct {
* X.509 certificate information
*/
typedef struct {
git_cert parent;
git_cert parent; /**< The parent cert */
/**
* Pointer to the X.509 certificate data
*/
void *data;
/**
* Length of the memory block pointed to by `data`.
*/
......@@ -144,14 +146,16 @@ typedef struct git_cred git_cred;
*/
struct git_cred {
git_credtype_t credtype; /**< A type of credential */
/** The deallocator for this type of credentials */
void GIT_CALLBACK(free)(git_cred *cred);
};
/** A plaintext username and password */
typedef struct {
git_cred parent;
char *username;
char *password;
git_cred parent; /**< The parent cred */
char *username; /**< The username to authenticate as */
char *password; /**< The password to use */
} git_cred_userpass_plaintext;
......@@ -172,33 +176,43 @@ typedef void GIT_CALLBACK(git_cred_ssh_interactive_cb)(const char* name, int nam
* A ssh key from disk
*/
typedef struct git_cred_ssh_key {
git_cred parent;
char *username;
char *publickey;
char *privatekey;
char *passphrase;
git_cred parent; /**< The parent cred */
char *username; /**< The username to authenticate as */
char *publickey; /**< The path to a public key */
char *privatekey; /**< The path to a private key */
char *passphrase; /**< Passphrase used to decrypt the private key */
} git_cred_ssh_key;
/**
* Keyboard-interactive based ssh authentication
*/
typedef struct git_cred_ssh_interactive {
git_cred parent;
char *username;
git_cred parent; /**< The parent cred */
char *username; /**< The username to authenticate as */
/**
* Callback used for authentication.
*/
git_cred_ssh_interactive_cb prompt_callback;
void *payload;
void *payload; /**< Payload passed to prompt_callback */
} git_cred_ssh_interactive;
/**
* A key with a custom signature function
*/
typedef struct git_cred_ssh_custom {
git_cred parent;
char *username;
char *publickey;
size_t publickey_len;
git_cred parent; /**< The parent cred */
char *username; /**< The username to authenticate as */
char *publickey; /**< The public key data */
size_t publickey_len; /**< Length of the public key */
/**
* Callback used to sign the data.
*/
git_cred_sign_cb sign_callback;
void *payload;
void *payload; /**< Payload passed to prompt_callback */
} git_cred_ssh_custom;
/** A key for NTLM/Kerberos "default" credentials */
......@@ -206,8 +220,8 @@ typedef struct git_cred git_cred_default;
/** Username-only credential information */
typedef struct git_cred_username {
git_cred parent;
char username[1];
git_cred parent; /**< The parent cred */
char username[1]; /**< The username to authenticate as */
} git_cred_username;
/**
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment