Merge pull request libgit2#6168 from punkymaniac/patch-documentation-2

Improve documentation

Author: ethomson

include/git2/apply.h

@@ -32,6 +32,8 @@ GIT_BEGIN_DECL
  *
  * @param delta The delta to be applied
  * @param payload User-specified payload
+ * @return 0 if the delta is applied, < 0 if the apply process will be aborted
+ *	or > 0 if the delta will not be applied.
  */
 typedef int GIT_CALLBACK(git_apply_delta_cb)(
 	const git_diff_delta *delta,
@@ -48,6 +50,8 @@ typedef int GIT_CALLBACK(git_apply_delta_cb)(
  *
  * @param hunk The hunk to be applied
  * @param payload User-specified payload
+ * @return 0 if the hunk is applied, < 0 if the apply process will be aborted
+ *	or > 0 if the hunk will not be applied.
  */
 typedef int GIT_CALLBACK(git_apply_hunk_cb)(
 	const git_diff_hunk *hunk,
@@ -89,6 +93,16 @@ typedef struct {
 #define GIT_APPLY_OPTIONS_VERSION 1
 #define GIT_APPLY_OPTIONS_INIT {GIT_APPLY_OPTIONS_VERSION}
 
+/**
+ * Initialize git_apply_options structure
+ *
+ * Initialize a `git_apply_options` with default values. Equivalent to creating
+ * an instance with GIT_APPLY_OPTIONS_INIT.
+ *
+ * @param opts The `git_apply_options` struct to initialize.
+ * @param version The struct version; pass `GIT_APPLY_OPTIONS_VERSION`
+ * @return 0 on success or -1 on failure.
+ */
 GIT_EXTERN(int) git_apply_options_init(git_apply_options *opts, unsigned int version);
 
 /**

include/git2/attr.h

@@ -177,6 +177,7 @@ typedef struct {
  *             not have to exist, but if it does not, then it will be
  *             treated as a plain file (not a directory).
  * @param name The name of the attribute to look up.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_attr_get(
 	const char **value_out,
@@ -199,6 +200,7 @@ GIT_EXTERN(int) git_attr_get(
  *             not have to exist, but if it does not, then it will be
  *             treated as a plain file (not a directory).
  * @param name The name of the attribute to look up.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_attr_get_ext(
 	const char **value_out,
@@ -235,6 +237,7 @@ GIT_EXTERN(int) git_attr_get_ext(
  *             it will be treated as a plain file (i.e. not a directory).
  * @param num_attr The number of attributes being looked up
  * @param names An array of num_attr strings containing attribute names.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_attr_get_many(
 	const char **values_out,
@@ -259,6 +262,7 @@ GIT_EXTERN(int) git_attr_get_many(
  *             it will be treated as a plain file (i.e. not a directory).
  * @param num_attr The number of attributes being looked up
  * @param names An array of num_attr strings containing attribute names.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_attr_get_many_ext(
 	const char **values_out,
@@ -349,6 +353,11 @@ GIT_EXTERN(int) git_attr_cache_flush(
  * macro, you would call:
  *
  *     git_attr_add_macro(repo, "binary", "-diff -crlf");
+ *
+ * @param repo The repository to add the macro in.
+ * @param name The name of the macro.
+ * @param values The value for the macro.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_attr_add_macro(
 	git_repository *repo,

include/git2/blame.h

@@ -203,6 +203,9 @@ typedef struct git_blame git_blame;
 
 /**
  * Gets the number of hunks that exist in the blame structure.
+ *
+ * @param blame The blame structure to query.
+ * @return The number of hunks.
  */
 GIT_EXTERN(uint32_t) git_blame_get_hunk_count(git_blame *blame);
 

include/git2/blob.h

@@ -302,6 +302,7 @@ GIT_EXTERN(int) git_blob_data_is_binary(const char *data, size_t len);
  *
  * @param out Pointer to store the copy of the object
  * @param source Original object to copy
+ * @return 0.
  */
 GIT_EXTERN(int) git_blob_dup(git_blob **out, git_blob *source);
 

include/git2/branch.h

@@ -34,6 +34,8 @@ GIT_BEGIN_DECL
  *
  * @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.

include/git2/commit.h

@@ -479,6 +479,7 @@ GIT_EXTERN(int) git_commit_create_buffer(
  * to the commit and write it into the given repository.
  *
  * @param out the resulting commit id
+ * @param repo the repository to create the commit in.
  * @param commit_content the content of the unsigned commit object
  * @param signature the signature to add to the commit. Leave `NULL`
  * to create a commit without adding a signature field.
@@ -499,6 +500,7 @@ GIT_EXTERN(int) git_commit_create_with_signature(
  *
  * @param out Pointer to store the copy of the commit
  * @param source Original commit to copy
+ * @return 0
  */
 GIT_EXTERN(int) git_commit_dup(git_commit **out, git_commit *source);
 

include/git2/common.h

@@ -167,6 +167,9 @@ typedef enum {
  * - GIT_FEATURE_SSH
  *   Libgit2 supports the SSH protocol for network operations. This requires
  *   the libssh2 library to be found when compiling libgit2
+ *
+ * - GIT_FEATURE_NSEC
+ *   Libgit2 supports the sub-second resolution in file modification times.
  */
 GIT_EXTERN(int) git_libgit2_features(void);
 

include/git2/config.h

@@ -72,14 +72,17 @@ typedef struct git_config_entry {
 
 /**
  * Free a config entry
+ *
+ * @param entry The entry to free.
  */
-GIT_EXTERN(void) git_config_entry_free(git_config_entry *);
+GIT_EXTERN(void) git_config_entry_free(git_config_entry *entry);
 
 /**
  * A config enumeration callback
  *
  * @param entry the entry currently being enumerated
  * @param payload a user-specified pointer
+ * @return non-zero to terminate the iteration.
  */
 typedef int GIT_CALLBACK(git_config_foreach_cb)(const git_config_entry *entry, void *payload);
 
@@ -269,6 +272,7 @@ GIT_EXTERN(int) git_config_open_level(
  *
  * @param out pointer in which to store the config object
  * @param config the config object in which to look
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_open_global(git_config **out, git_config *config);
 
@@ -422,6 +426,7 @@ GIT_EXTERN(int) git_config_get_string_buf(git_buf *out, const git_config *cfg, c
  * interested in. Use NULL to indicate all
  * @param callback the function to be called on each value of the variable
  * @param payload opaque pointer to pass to the callback
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_get_multivar_foreach(const git_config *cfg, const char *name, const char *regexp, git_config_foreach_cb callback, void *payload);
 
@@ -437,6 +442,7 @@ GIT_EXTERN(int) git_config_get_multivar_foreach(const git_config *cfg, const cha
  * @param name the variable's name
  * @param regexp regular expression to filter which variables we're
  * interested in. Use NULL to indicate all
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_multivar_iterator_new(git_config_iterator **out, const git_config *cfg, const char *name, const char *regexp);
 
@@ -515,6 +521,7 @@ GIT_EXTERN(int) git_config_set_string(git_config *cfg, const char *name, const c
  * @param name the variable's name
  * @param regexp a regular expression to indicate which values to replace
  * @param value the new value.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_set_multivar(git_config *cfg, const char *name, const char *regexp, const char *value);
 
@@ -524,6 +531,7 @@ GIT_EXTERN(int) git_config_set_multivar(git_config *cfg, const char *name, const
  *
  * @param cfg the configuration
  * @param name the variable to delete
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_delete_entry(git_config *cfg, const char *name);
 
@@ -568,7 +576,8 @@ GIT_EXTERN(int) git_config_foreach(
  * `git_config_iterator_free` when done.
  *
  * @param out pointer to store the iterator
- * @param cfg where to ge the variables from
+ * @param cfg where to get the variables from
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_iterator_new(git_config_iterator **out, const git_config *cfg);
 
@@ -585,6 +594,7 @@ GIT_EXTERN(int) git_config_iterator_new(git_config_iterator **out, const git_con
  * @param out pointer to store the iterator
  * @param cfg where to ge the variables from
  * @param regexp regular expression to match the names
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator **out, const git_config *cfg, const char *regexp);
 
@@ -662,6 +672,7 @@ GIT_EXTERN(int) git_config_get_mapped(
  * @param maps array of `git_configmap` objects specifying the possible mappings
  * @param map_n number of mapping objects in `maps`
  * @param value value to parse
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_lookup_map_value(
 	int *out,
@@ -678,6 +689,7 @@ GIT_EXTERN(int) git_config_lookup_map_value(
  *
  * @param out place to store the result of the parsing
  * @param value value to parse
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value);
 
@@ -690,6 +702,7 @@ GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value);
  *
  * @param out place to store the result of the parsing
  * @param value value to parse
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value);
 
@@ -702,6 +715,7 @@ GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value);
  *
  * @param out place to store the result of the parsing
  * @param value value to parse
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value);
 
@@ -717,6 +731,7 @@ GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value);
  *
  * @param out placae to store the result of parsing
  * @param value the path to evaluate
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_parse_path(git_buf *out, const char *value);
 
@@ -735,6 +750,7 @@ GIT_EXTERN(int) git_config_parse_path(git_buf *out, const char *value);
  * @param regexp regular expression to match against config names (can be NULL)
  * @param callback the function to call on each variable
  * @param payload the data to pass to the callback
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_config_backend_foreach_match(
 	git_config_backend *backend,

include/git2/credential.h

@@ -254,6 +254,7 @@ typedef void GIT_CALLBACK(git_credential_ssh_interactive_cb)(
  * Create a new ssh keyboard-interactive based credential object.
  * The supplied credential parameter will be internally duplicated.
  *
+ * @param out The newly created credential object.
  * @param username Username to use to authenticate.
  * @param prompt_callback The callback method used for prompts.
  * @param payload Additional data to pass to the callback.

include/git2/credential_helpers.h

@@ -39,6 +39,7 @@ typedef struct git_credential_userpass_payload {
  * @param allowed_types A bitmask stating which credential types are OK to return.
  * @param payload The payload provided when specifying this callback.  (This is
  *        interpreted as a `git_credential_userpass_payload*`.)
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_credential_userpass(
 		git_credential **out,