Merge pull request libgit2#4827 from tiennou/fix/documentation-fixups

Documentation fixups

Author: pks-t

include/git2/checkout.h

@@ -67,7 +67,7 @@ GIT_BEGIN_DECL
  * To emulate `git checkout -f`, use `GIT_CHECKOUT_FORCE`.
  *
  *
- * There are some additional flags to modified the behavior of checkout:
+ * There are some additional flags to modify the behavior of checkout:
  *
  * - GIT_CHECKOUT_ALLOW_CONFLICTS makes SAFE mode apply safe file updates
  *   even if there are conflicts (instead of cancelling the checkout).

include/git2/config.h

@@ -75,7 +75,17 @@ typedef struct git_config_entry {
  */
 GIT_EXTERN(void) git_config_entry_free(git_config_entry *);
 
-typedef int  (*git_config_foreach_cb)(const git_config_entry *, void *);
+/**
+ * A config enumeration callback
+ *
+ * @param entry the entry currently being enumerated
+ * @param payload a user-specified pointer
+ */
+typedef int  (*git_config_foreach_cb)(const git_config_entry *entry, void *payload);
+
+/**
+ * An opaque structure for a configuration iterator
+ */
 typedef struct git_config_iterator git_config_iterator;
 
 /**
@@ -252,7 +262,7 @@ GIT_EXTERN(int) git_config_open_level(
  * Open the global/XDG configuration file according to git's rules
  *
  * Git allows you to store your global configuration at
- * `$HOME/.config` or `$XDG_CONFIG_HOME/git/config`. For backwards
+ * `$HOME/.gitconfig` or `$XDG_CONFIG_HOME/git/config`. For backwards
  * compatability, the XDG file shouldn't be used unless the use has
  * created it explicitly. With this function you'll open the correct
  * one to write to.
@@ -581,7 +591,7 @@ GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator **out, const gi
 /**
  * Perform an operation on each config variable matching a regular expression.
  *
- * This behaviors like `git_config_foreach` with an additional filter of a
+ * This behaves like `git_config_foreach` with an additional filter of a
  * regular expression that filters which config keys are passed to the
  * callback.
  *
@@ -711,11 +721,11 @@ GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value);
 GIT_EXTERN(int) git_config_parse_path(git_buf *out, const char *value);
 
 /**
- * Perform an operation on each config variable in given config backend
+ * Perform an operation on each config variable in a given config backend,
  * matching a regular expression.
  *
- * This behaviors like `git_config_foreach_match` except instead of all config
- * entries it just enumerates through the given backend entry.
+ * This behaves like `git_config_foreach_match` except that only config
+ * entries from the given backend entry are enumerated.
  *
  * The regular expression is applied case-sensitively on the normalized form of
  * the variable name: the section and variable parts are lower-cased. The

include/git2/transport.h

@@ -77,44 +77,73 @@ typedef struct {
  *** Begin interface for credentials acquisition ***
  */
 
-/** Authentication type requested */
+/**
+ * Supported credential types
+ *
+ * This represents the various types of authentication methods supported by
+ * the library.
+ */
 typedef enum {
-	/* git_cred_userpass_plaintext */
+	/**
+	 * A vanilla user/password request
+	 * @see git_cred_userpass_plaintext_new
+	 */
 	GIT_CREDTYPE_USERPASS_PLAINTEXT = (1u << 0),
 
-	/* git_cred_ssh_key */
+	/**
+	 * An SSH key-based authentication request
+	 * @see git_cred_ssh_key_new
+	 */
 	GIT_CREDTYPE_SSH_KEY = (1u << 1),
 
-	/* git_cred_ssh_custom */
+	/**
+	 * An SSH key-based authentication request, with a custom signature
+	 * @see git_cred_ssh_custom_new
+	 */
 	GIT_CREDTYPE_SSH_CUSTOM = (1u << 2),
 
-	/* git_cred_default */
+	/**
+	 * An NTLM/Negotiate-based authentication request.
+	 * @see git_cred_default
+	 */
 	GIT_CREDTYPE_DEFAULT = (1u << 3),
 
-	/* git_cred_ssh_interactive */
+	/**
+	 * An SSH interactive authentication request
+	 * @see git_cred_ssh_interactive_new
+	 */
 	GIT_CREDTYPE_SSH_INTERACTIVE = (1u << 4),
 
 	/**
-	 * Username-only information
+	 * Username-only authentication request
 	 *
-	 * If the SSH transport does not know which username to use,
-	 * it will ask via this credential type.
+	 * Used as a pre-authentication step if the underlying transport
+	 * (eg. SSH, with no username in its URL) does not know which username
+	 * to use.
+	 *
+	 * @see git_cred_username_new
 	 */
 	GIT_CREDTYPE_USERNAME = (1u << 5),
 
 	/**
-	 * Credentials read from memory.
+	 * An SSH key-based authentication request
+	 *
+	 * Allows credentials to be read from memory instead of files.
+	 * Note that because of differences in crypto backend support, it might
+	 * not be functional.
 	 *
-	 * Only available for libssh2+OpenSSL for now.
+	 * @see git_cred_ssh_key_memory_new
 	 */
 	GIT_CREDTYPE_SSH_MEMORY = (1u << 6),
 } git_credtype_t;
 
-/* The base structure for all credential types */
 typedef struct git_cred git_cred;
 
+/**
+ * The base structure for all credential types
+ */
 struct git_cred {
-	git_credtype_t credtype;
+	git_credtype_t credtype; /**< A type of credential */
 	void (*free)(git_cred *cred);
 };