Add documentation about parameter and return value

30 files changed, 122 insertions, 0 deletions

diff --git a/include/git2/apply.h b/include/git2/apply.h
index 0aa2b24e6..db652bde0 100644
--- a/include/git2/apply.h
+++ b/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,
diff --git a/include/git2/attr.h b/include/git2/attr.h
index 157192c9d..c93055083 100644
--- a/include/git2/attr.h
+++ b/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 where to add the macro.
+ * @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,
diff --git a/include/git2/blame.h b/include/git2/blame.h
index 33a9fbc98..cb961a562 100644
--- a/include/git2/blame.h
+++ b/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);
 
diff --git a/include/git2/blob.h b/include/git2/blob.h
index 59fac9e20..6db85f38d 100644
--- a/include/git2/blob.h
+++ b/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);
 
diff --git a/include/git2/branch.h b/include/git2/branch.h
index 24ea7f7d0..071622d83 100644
--- a/include/git2/branch.h
+++ b/include/git2/branch.h
@@ -34,6 +34,8 @@ GIT_BEGIN_DECL
  *
  * @param out Pointer where to store the underlying reference.
  *
+ * @param repository the repository where to create the branch.
+ *
  * @param branch_name Name for the branch; this name is
  * validated for consistency. It should also not conflict with
  * an already existing branch name.
diff --git a/include/git2/commit.h b/include/git2/commit.h
index 4d74b8994..29e7271ea 100644
--- a/include/git2/commit.h
+++ b/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 repository the repository where to create the commit.
  * @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);
 
diff --git a/include/git2/config.h b/include/git2/config.h
index 202d36a7e..b3eccbb17 100644
--- a/include/git2/config.h
+++ b/include/git2/config.h
@@ -72,6 +72,8 @@ 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 *entry);
 
@@ -80,6 +82,7 @@ GIT_EXTERN(void) git_config_entry_free(git_config_entry *entry);
  *
  * @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 non-zero to terminate the iteration.
  */
 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 non-zero to terminate the iteration.
  */
 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);
 
@@ -569,6 +577,7 @@ GIT_EXTERN(int) git_config_foreach(
  *
  * @param out pointer to store the iterator
  * @param cfg where to ge 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 non-zero to terminate the iteration.
  */
 GIT_EXTERN(int) git_config_backend_foreach_match(
 	git_config_backend *backend,
diff --git a/include/git2/credential.h b/include/git2/credential.h
index a4e68e853..7a04bc064 100644
--- a/include/git2/credential.h
+++ b/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.
diff --git a/include/git2/credential_helpers.h b/include/git2/credential_helpers.h
index 9a70ecb38..f0fb07041 100644
--- a/include/git2/credential_helpers.h
+++ b/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,
diff --git a/include/git2/describe.h b/include/git2/describe.h
index e8afd6879..8392ee86e 100644
--- a/include/git2/describe.h
+++ b/include/git2/describe.h
@@ -142,6 +142,7 @@ typedef struct git_describe_result git_describe_result;
  * you're done with it.
  * @param committish a committish to describe
  * @param opts the lookup options (or NULL for defaults)
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_describe_commit(
 	git_describe_result **result,
@@ -159,6 +160,7 @@ GIT_EXTERN(int) git_describe_commit(
  * you're done with it.
  * @param repo the repository in which to perform the describe
  * @param opts the lookup options (or NULL for defaults)
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_describe_workdir(
 	git_describe_result **out,
@@ -172,6 +174,7 @@ GIT_EXTERN(int) git_describe_workdir(
  * @param result the result from `git_describe_commit()` or
  * `git_describe_workdir()`.
  * @param opts the formatting options (or NULL for defaults)
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_describe_format(
 	git_buf *out,
@@ -180,6 +183,8 @@ GIT_EXTERN(int) git_describe_format(
 
 /**
  * Free the describe result.
+ *
+ * @param result The result to free.
  */
 GIT_EXTERN(void) git_describe_result_free(git_describe_result *result);
 
diff --git a/include/git2/diff.h b/include/git2/diff.h
index c040cd190..b847c15d2 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -831,6 +831,7 @@ GIT_EXTERN(void) git_diff_free(git_diff *diff);
  * @param old_tree A git_tree object to diff from, or NULL for empty tree.
  * @param new_tree A git_tree object to diff to, or NULL for empty tree.
  * @param opts Structure with options to influence diff or NULL for defaults.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_diff_tree_to_tree(
 	git_diff **diff,
@@ -857,6 +858,7 @@ GIT_EXTERN(int) git_diff_tree_to_tree(
  * @param old_tree A git_tree object to diff from, or NULL for empty tree.
  * @param index The index to diff with; repo index used if NULL.
  * @param opts Structure with options to influence diff or NULL for defaults.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_diff_tree_to_index(
 	git_diff **diff,
@@ -884,6 +886,7 @@ GIT_EXTERN(int) git_diff_tree_to_index(
  * @param repo The repository.
  * @param index The index to diff from; repo index used if NULL.
  * @param opts Structure with options to influence diff or NULL for defaults.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_diff_index_to_workdir(
 	git_diff **diff,
@@ -913,6 +916,7 @@ GIT_EXTERN(int) git_diff_index_to_workdir(
  * @param repo The repository containing the tree.
  * @param old_tree A git_tree object to diff from, or NULL for empty tree.
  * @param opts Structure with options to influence diff or NULL for defaults.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_diff_tree_to_workdir(
 	git_diff **diff,
@@ -932,6 +936,7 @@ GIT_EXTERN(int) git_diff_tree_to_workdir(
  * @param repo The repository containing the tree.
  * @param old_tree A git_tree object to diff from, or NULL for empty tree.
  * @param opts Structure with options to influence diff or NULL for defaults.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_diff_tree_to_workdir_with_index(
 	git_diff **diff,
@@ -950,6 +955,7 @@ GIT_EXTERN(int) git_diff_tree_to_workdir_with_index(
  * @param old_index A git_index object to diff from.
  * @param new_index A git_index object to diff to.
  * @param opts Structure with options to influence diff or NULL for defaults.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_diff_index_to_index(
 	git_diff **diff,
@@ -970,6 +976,7 @@ GIT_EXTERN(int) git_diff_index_to_index(
  *
  * @param onto Diff to merge into.
  * @param from Diff to merge.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_diff_merge(
 	git_diff *onto,
diff --git a/include/git2/filter.h b/include/git2/filter.h
index 632bb84e3..79bf14ce5 100644
--- a/include/git2/filter.h
+++ b/include/git2/filter.h
@@ -196,6 +196,7 @@ GIT_EXTERN(int) git_filter_list_apply_to_buffer(
  * @param repo the repository in which to perform the filtering
  * @param path the path of the file to filter, a relative path will be
  * taken as relative to the workdir
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_filter_list_apply_to_file(
 	git_buf *out,
@@ -209,6 +210,7 @@ GIT_EXTERN(int) git_filter_list_apply_to_file(
  * @param out buffer into which to store the filtered file
  * @param filters the list of filters to apply
  * @param blob the blob to filter
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_filter_list_apply_to_blob(
 	git_buf *out,
@@ -222,6 +224,7 @@ GIT_EXTERN(int) git_filter_list_apply_to_blob(
  * @param buffer the buffer to filter
  * @param len the size of the buffer
  * @param target the stream into which the data will be written
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_filter_list_stream_buffer(
 	git_filter_list *filters,
@@ -237,6 +240,7 @@ GIT_EXTERN(int) git_filter_list_stream_buffer(
  * @param path the path of the file to filter, a relative path will be
  * taken as relative to the workdir
  * @param target the stream into which the data will be written
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_filter_list_stream_file(
 	git_filter_list *filters,
@@ -250,6 +254,7 @@ GIT_EXTERN(int) git_filter_list_stream_file(
  * @param filters the list of filters to apply
  * @param blob the blob to filter
  * @param target the stream into which the data will be written
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_filter_list_stream_blob(
 	git_filter_list *filters,
diff --git a/include/git2/graph.h b/include/git2/graph.h
index 712ae474a..56edb2f87 100644
--- a/include/git2/graph.h
+++ b/include/git2/graph.h
@@ -33,6 +33,7 @@ GIT_BEGIN_DECL
  * @param repo the repository where the commits exist
  * @param local the commit for local
  * @param upstream the commit for upstream
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_graph_ahead_behind(size_t *ahead, size_t *behind, git_repository *repo, const git_oid *local, const git_oid *upstream);
 
diff --git a/include/git2/index.h b/include/git2/index.h
index 5864791e6..3cf64d827 100644
--- a/include/git2/index.h
+++ b/include/git2/index.h
@@ -491,6 +491,7 @@ GIT_EXTERN(int) git_index_entry_is_conflict(const git_index_entry *entry);
  *
  * @param iterator_out The newly created iterator
  * @param index The index to iterate
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_index_iterator_new(
 	git_index_iterator **iterator_out,
@@ -787,6 +788,7 @@ GIT_EXTERN(int) git_index_conflict_cleanup(git_index *index);
 /**
  * Determine if the index contains entries representing file conflicts.
  *
+ * @param index An existing index object.
  * @return 1 if at least one conflict is found, 0 otherwise.
  */
 GIT_EXTERN(int) git_index_has_conflicts(const git_index *index);
@@ -811,6 +813,7 @@ GIT_EXTERN(int) git_index_conflict_iterator_new(
  * @param ancestor_out Pointer to store the ancestor side of the conflict
  * @param our_out Pointer to store our side of the conflict
  * @param their_out Pointer to store their side of the conflict
+ * @param iterator The conflict iterator.
  * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code
  *         (negative value)
  */
diff --git a/include/git2/indexer.h b/include/git2/indexer.h
index a434d243f..8af02a6c0 100644
--- a/include/git2/indexer.h
+++ b/include/git2/indexer.h
@@ -98,6 +98,7 @@ GIT_EXTERN(int) git_indexer_options_init(
  * will be returned if there are bases missing)
  * @param opts Optional structure containing additional options. See
  * `git_indexer_options` above.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_indexer_new(
 		git_indexer **out,
@@ -113,6 +114,7 @@ GIT_EXTERN(int) git_indexer_new(
  * @param data the data to add
  * @param size the size of the data in bytes
  * @param stats stat storage
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_indexer_append(git_indexer *idx, const void *data, size_t size, git_indexer_progress *stats);
 
@@ -122,6 +124,8 @@ GIT_EXTERN(int) git_indexer_append(git_indexer *idx, const void *data, size_t si
  * Resolve any pending deltas and write out the index file
  *
  * @param idx the indexer
+ * @param stats Stat storage.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_indexer_commit(git_indexer *idx, git_indexer_progress *stats);
 
@@ -132,6 +136,8 @@ GIT_EXTERN(int) git_indexer_commit(git_indexer *idx, git_indexer_progress *stats
  * names. This is only correct after the index has been finalized.
  *
  * @param idx the indexer instance
+ * @return the packfile's hash. In casewhere the index has not been finalized,
+ *	it will be zeroed out.
  */
 GIT_EXTERN(const git_oid *) git_indexer_hash(const git_indexer *idx);
 
diff --git a/include/git2/merge.h b/include/git2/merge.h
index e32c53fcc..3b3132f26 100644
--- a/include/git2/merge.h
+++ b/include/git2/merge.h
@@ -372,6 +372,7 @@ typedef enum {
  * merging them into the HEAD of the repository.
  *
  * @param analysis_out analysis enumeration that the result is written into
+ * @param preference_out One of the `git_merge_preference_t` flag.
  * @param repo the repository to merge
  * @param their_heads the heads to merge into
  * @param their_heads_len the number of heads to merge
@@ -389,6 +390,7 @@ GIT_EXTERN(int) git_merge_analysis(
  * merging them into a reference.
  *
  * @param analysis_out analysis enumeration that the result is written into
+ * @param preference_out One of the `git_merge_preference_t` flag.
  * @param repo the repository to merge
  * @param our_ref the reference to perform the analysis from
  * @param their_heads the heads to merge into
diff --git a/include/git2/message.h b/include/git2/message.h
index 42ca3e5c2..cd3ddf730 100644
--- a/include/git2/message.h
+++ b/include/git2/message.h
@@ -75,6 +75,8 @@ GIT_EXTERN(int) git_message_trailers(git_message_trailer_array *arr, const char
 /**
  * Clean's up any allocated memory in the git_message_trailer_array filled by
  * a call to git_message_trailers.
+ *
+ * @param arr The trailer to free.
  */
 GIT_EXTERN(void) git_message_trailer_array_free(git_message_trailer_array *arr);
 
diff --git a/include/git2/object.h b/include/git2/object.h
index dbf480ed6..2692a4056 100644
--- a/include/git2/object.h
+++ b/include/git2/object.h
@@ -221,6 +221,7 @@ GIT_EXTERN(int) git_object_peel(
  *
  * @param dest Pointer to store the copy of the object
  * @param source Original object to copy
+ * @return 0
  */
 GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source);
 
diff --git a/include/git2/odb.h b/include/git2/odb.h
index 0691aa4d0..c7c3a88a5 100644
--- a/include/git2/odb.h
+++ b/include/git2/odb.h
@@ -345,6 +345,11 @@ GIT_EXTERN(int) git_odb_stream_finalize_write(git_oid *out, git_odb_stream *stre
  * Read from an odb stream
  *
  * Most backends don't implement streaming reads
+ *
+ * @param stream the stream
+ * @param buffer the buffer where to store the readed data.
+ * @param len the buffer's length
+ * @return 0 if the read succeeded, error code otherwise
  */
 GIT_EXTERN(int) git_odb_stream_read(git_odb_stream *stream, char *buffer, size_t len);
 
@@ -405,6 +410,7 @@ GIT_EXTERN(int) git_odb_open_rstream(
  * Be aware that this is called inline with network and indexing operations,
  * so performance may be affected.
  * @param progress_payload payload for the progress callback
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_odb_write_pack(
 	git_odb_writepack **out,
@@ -422,6 +428,7 @@ GIT_EXTERN(int) git_odb_write_pack(
  * exist).
  *
  * @param db object database where the `multi-pack-index` file will be written.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_odb_write_multi_pack_index(
 	git_odb *db);
diff --git a/include/git2/pack.h b/include/git2/pack.h
index cd28a4f5b..253a860cd 100644
--- a/include/git2/pack.h
+++ b/include/git2/pack.h
@@ -148,6 +148,7 @@ GIT_EXTERN(int) git_packbuilder_insert_recur(git_packbuilder *pb, const git_oid
  *
  * @param buf Buffer where to write the packfile
  * @param pb The packbuilder
+ * @return 0 or an error code
  */
 GIT_EXTERN(int) git_packbuilder_write_buf(git_buf *buf, git_packbuilder *pb);
 
@@ -176,6 +177,7 @@ GIT_EXTERN(int) git_packbuilder_write(
 * names. This is only correct after the packfile has been written.
 *
 * @param pb The packbuilder object
+ * @return 0 or an error code
 */
 GIT_EXTERN(const git_oid *) git_packbuilder_hash(git_packbuilder *pb);
 
diff --git a/include/git2/patch.h b/include/git2/patch.h
index fde9659e7..9cf758a3e 100644
--- a/include/git2/patch.h
+++ b/include/git2/patch.h
@@ -139,17 +139,25 @@ GIT_EXTERN(int) git_patch_from_buffers(
 
 /**
  * Free a git_patch object.
+ *
+ * @param patch The patch to free.
  */
 GIT_EXTERN(void) git_patch_free(git_patch *patch);
 
 /**
  * Get the delta associated with a patch.  This delta points to internal
  * data and you do not have to release it when you are done with it.
+ *
+ * @param patch The patch in which to get the delta.
+ * @return The delta associated with the patch.
  */
 GIT_EXTERN(const git_diff_delta *) git_patch_get_delta(const git_patch *patch);
 
 /**
  * Get the number of hunks in a patch
+ *
+ * @param patch The patch in which to get the number of hunks.
+ * @return The number of hunks of the patch.
  */
 GIT_EXTERN(size_t) git_patch_num_hunks(const git_patch *patch);
 
diff --git a/include/git2/rebase.h b/include/git2/rebase.h
index 2a5dece7c..5edd443d1 100644
--- a/include/git2/rebase.h
+++ b/include/git2/rebase.h
@@ -242,6 +242,7 @@ GIT_EXTERN(int) git_rebase_open(
 /**
  * Gets the original `HEAD` ref name for merge rebases.
  *
+ * @param rebase The in-progress rebase.
  * @return The original `HEAD` ref name
  */
 GIT_EXTERN(const char *) git_rebase_orig_head_name(git_rebase *rebase);
@@ -249,6 +250,7 @@ GIT_EXTERN(const char *) git_rebase_orig_head_name(git_rebase *rebase);
 /**
  * Gets the original `HEAD` id for merge rebases.
  *
+ * @param rebase The in-progress rebase.
  * @return The original `HEAD` id
  */
 GIT_EXTERN(const git_oid *) git_rebase_orig_head_id(git_rebase *rebase);
@@ -256,6 +258,7 @@ GIT_EXTERN(const git_oid *) git_rebase_orig_head_id(git_rebase *rebase);
 /**
  * Gets the `onto` ref name for merge rebases.
  *
+ * @param rebase The in-progress rebase.
  * @return The `onto` ref name
  */
 GIT_EXTERN(const char *) git_rebase_onto_name(git_rebase *rebase);
@@ -263,6 +266,7 @@ GIT_EXTERN(const char *) git_rebase_onto_name(git_rebase *rebase);
 /**
  * Gets the `onto` id for merge rebases.
  *
+ * @param rebase The in-progress rebase.
  * @return The `onto` id
  */
 GIT_EXTERN(const git_oid *) git_rebase_onto_id(git_rebase *rebase);
@@ -322,6 +326,10 @@ GIT_EXTERN(int) git_rebase_next(
  * This is only applicable for in-memory rebases; for rebases within
  * a working directory, the changes were applied to the repository's
  * index.
+ *
+ * @param index The result index of the last operation.
+ * @param rebase The in-progress rebase.
+ * @return 0
  */
 GIT_EXTERN(int) git_rebase_inmemory_index(
 	git_index **index,
diff --git a/include/git2/refdb.h b/include/git2/refdb.h
index a315876ae..c4849abdc 100644
--- a/include/git2/refdb.h
+++ b/include/git2/refdb.h
@@ -52,6 +52,9 @@ GIT_EXTERN(int) git_refdb_open(git_refdb **out, git_repository *repo);
  * Suggests that the given refdb compress or optimize its references.
  * This mechanism is implementation specific.  For on-disk reference
  * databases, for example, this may pack all loose references.
+ *
+ * @param refdb The reference database to optimize.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_refdb_compress(git_refdb *refdb);
 
diff --git a/include/git2/remote.h b/include/git2/remote.h
index 088f528a6..0527fad3e 100644
--- a/include/git2/remote.h
+++ b/include/git2/remote.h
@@ -300,6 +300,7 @@ GIT_EXTERN(int) git_remote_add_fetch(git_repository *repo, const char *remote, c
  *
  * @param array pointer to the array in which to store the strings
  * @param remote the remote to query
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_remote_get_fetch_refspecs(git_strarray *array, const git_remote *remote);
 
@@ -324,6 +325,7 @@ GIT_EXTERN(int) git_remote_add_push(git_repository *repo, const char *remote, co
  *
  * @param array pointer to the array in which to store the strings
  * @param remote the remote to query
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_remote_get_push_refspecs(git_strarray *array, const git_remote *remote);
 
@@ -899,6 +901,7 @@ GIT_EXTERN(int) git_remote_prune(git_remote *remote, const git_remote_callbacks
  * @param refspecs the refspecs to use for pushing. If NULL or an empty
  *                 array, the configured refspecs will be used
  * @param opts options to use for this push
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_remote_push(git_remote *remote,
 				const git_strarray *refspecs,
diff --git a/include/git2/repository.h b/include/git2/repository.h
index 8bd877be4..6692537d4 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -673,6 +673,9 @@ GIT_EXTERN(int) git_repository_message(git_buf *out, git_repository *repo);
  * Remove git's prepared message.
  *
  * Remove the message that `git_repository_message` retrieves.
+ *
+ * @param repo Repository to remove prepared message from.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_repository_message_remove(git_repository *repo);
 
@@ -928,6 +931,7 @@ GIT_EXTERN(int) git_repository_is_shallow(git_repository *repo);
  * @param name where to store the pointer to the name
  * @param email where to store the pointer to the email
  * @param repo the repository
+ * @return 0
  */
 GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, const git_repository *repo);
 
@@ -941,6 +945,7 @@ GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, cons
  * @param repo the repository to configure
  * @param name the name to use for the reflog entries
  * @param email the email to use for the reflog entries
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name, const char *email);
 
diff --git a/include/git2/revwalk.h b/include/git2/revwalk.h
index 241479d56..b8655e50f 100644
--- a/include/git2/revwalk.h
+++ b/include/git2/revwalk.h
@@ -249,6 +249,7 @@ GIT_EXTERN(int) git_revwalk_push_range(git_revwalk *walk, const char *range);
  *
  * No parents other than the first for each commit will be enqueued.
  *
+ * @param walk The revisionwlaker.
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_revwalk_simplify_first_parent(git_revwalk *walk);
@@ -277,6 +278,7 @@ GIT_EXTERN(git_repository *) git_revwalk_repository(git_revwalk *walk);
  *
  * @param commit_id oid of Commit
  * @param payload User-specified pointer to data to be passed as data payload
+ * @return non-zero to hide the commmit and it parrent.
  */
 typedef int GIT_CALLBACK(git_revwalk_hide_cb)(
 	const git_oid *commit_id,
@@ -288,6 +290,7 @@ typedef int GIT_CALLBACK(git_revwalk_hide_cb)(
  * @param walk the revision walker
  * @param hide_cb  callback function to hide a commit and its parents
  * @param payload  data payload to be passed to callback function
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_revwalk_add_hide_cb(
 	git_revwalk *walk,
diff --git a/include/git2/submodule.h b/include/git2/submodule.h
index c6eeb96dc..ed44e3dcf 100644
--- a/include/git2/submodule.h
+++ b/include/git2/submodule.h
@@ -229,6 +229,7 @@ GIT_EXTERN(int) git_submodule_lookup(
  *
  * @param out Pointer to store the copy of the submodule.
  * @param source Original submodule to copy.
+ * @return 0
  */
 GIT_EXTERN(int) git_submodule_dup(git_submodule **out, git_submodule *source);
 
@@ -320,6 +321,7 @@ GIT_EXTERN(int) git_submodule_clone(
  * (but doesn't actually do the commit).
  *
  * @param submodule The submodule to finish adding.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_submodule_add_finalize(git_submodule *submodule);
 
@@ -589,6 +591,9 @@ GIT_EXTERN(int) git_submodule_repo_init(
  * submodule config, acting like "git submodule sync".  This is useful if
  * you have altered the URL for the submodule (or it has been altered by a
  * fetch of upstream changes) and you need to update your local repo.
+ *
+ * @param submodule The submodule to copy.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_submodule_sync(git_submodule *submodule);
 
diff --git a/include/git2/tag.h b/include/git2/tag.h
index a3921369d..983053655 100644
--- a/include/git2/tag.h
+++ b/include/git2/tag.h
@@ -362,6 +362,7 @@ GIT_EXTERN(int) git_tag_peel(
  *
  * @param out Pointer to store the copy of the tag
  * @param source Original tag to copy
+ * @return 0
  */
 GIT_EXTERN(int) git_tag_dup(git_tag **out, git_tag *source);
 
diff --git a/include/git2/tree.h b/include/git2/tree.h
index db24bf6ed..db7706eed 100644
--- a/include/git2/tree.h
+++ b/include/git2/tree.h
@@ -418,6 +418,7 @@ GIT_EXTERN(int) git_tree_walk(
  *
  * @param out Pointer to store the copy of the tree
  * @param source Original tree to copy
+ * @return 0
  */
 GIT_EXTERN(int) git_tree_dup(git_tree **out, git_tree *source);
 
diff --git a/include/git2/worktree.h b/include/git2/worktree.h
index 8691f96db..bb024dc94 100644
--- a/include/git2/worktree.h
+++ b/include/git2/worktree.h
@@ -52,6 +52,7 @@ GIT_EXTERN(int) git_worktree_lookup(git_worktree **out, git_repository *repo, co
  *
  * @param out Out-pointer for the newly allocated worktree
  * @param repo Repository to look up worktree for
+ * @return 0 or an error code
  */
 GIT_EXTERN(int) git_worktree_open_from_repository(git_worktree **out, git_repository *repo);
 
@@ -237,6 +238,10 @@ GIT_EXTERN(int) git_worktree_prune_options_init(
  * If the worktree is not valid and not locked or if the above
  * flags have been passed in, this function will return a
  * positive value.
+ *
+ * @param wt Worktree to check.
+ * @param opts The prunable options.
+ * @return 1 if the worktree is prunable, 0 otherwise, or an error code.
  */
 GIT_EXTERN(int) git_worktree_is_prunable(git_worktree *wt,
 	git_worktree_prune_options *opts);