Merge pull request libgit2#5128 from tiennou/fix/docs

More documentation

Author: pks-t

include/git2/apply.h

@@ -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;
 

include/git2/buffer.h

@@ -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;
 
 /**

include/git2/checkout.h

@@ -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;
 

include/git2/remote.h

@@ -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

include/git2/status.h

@@ -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;
 

include/git2/sys/alloc.h

@@ -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.
 	 */

include/git2/transport.h

@@ -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,42 +176,52 @@ 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 */
 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;
 
 /**