Fixed most documentation header bugs

Fixed a few header @param and @return typos with the help of -Wdocumentation in Xcode.

The following warnings have not been fixed:
common.h:213 - Not sure how the documentation format is for '...'
notes.h:102 - Correct @param name but empty text
notes.h:111 - Correct @param name but empty text
pack.h:140 - @return missing text
pack.h:148 - @return missing text

include/git2/attr.h

@@ -162,7 +162,7 @@ GIT_EXTERN(int) git_attr_get(
  * Then you could loop through the 3 values to get the settings for
  * the three attributes you asked about.
  *
- * @param values An array of num_attr entries that will have string
+ * @param values_out An array of num_attr entries that will have string
  *             pointers written into it for the values of the attributes.
  *             You should not modify or free the values that are written
  *             into this array (although of course, you should free the

include/git2/commit.h

@@ -235,7 +235,7 @@ GIT_EXTERN(int) git_commit_nth_gen_ancestor(
  *
  * @param parent_count Number of parents for this commit
  *
- * @param parents[] Array of `parent_count` pointers to `git_commit`
+ * @param parents Array of `parent_count` pointers to `git_commit`
  *  objects that will be used as the parents for this commit. This
  *  array may be NULL if `parent_count` is 0 (root commit). All the
  *  given commits must be owned by the `repo`.

include/git2/config.h

@@ -119,7 +119,7 @@ GIT_EXTERN(int) git_config_find_xdg(char *out, size_t length);
  * If /etc/gitconfig doesn't exist, it will look for
  * %PROGRAMFILES%\Git\etc\gitconfig.
 
- * @param global_config_path Buffer to store the path in
+ * @param out Buffer to store the path in
  * @param length size of the buffer in bytes
  * @return 0 if a system configuration file has been
  *	found. Its path will be stored in `buffer`.
@@ -335,8 +335,8 @@ GIT_EXTERN(int) git_config_get_string(const char **out, const git_config *cfg, c
  * @param name the variable's name
  * @param regexp regular expression to filter which variables we're
  * interested in. Use NULL to indicate all
- * @param fn the function to be called on each value of the variable
- * @param data opaque pointer to pass to the callback
+ * @param callback the function to be called on each value of the variable
+ * @param payload opaque pointer to pass to the callback
  */
 GIT_EXTERN(int) git_config_get_multivar(const git_config *cfg, const char *name, const char *regexp, git_config_foreach_cb callback, void *payload);
 

include/git2/diff.h

@@ -747,7 +747,7 @@ GIT_EXTERN(int) git_diff_print_raw(
  * letters for your own purposes.  This function does just that.  By the
  * way, unmodified will return a space (i.e. ' ').
  *
- * @param delta_t The git_delta_t value to look up
+ * @param status The git_delta_t value to look up
  * @return The single character label for that code
  */
 GIT_EXTERN(char) git_diff_status_char(git_delta_t status);
@@ -918,7 +918,7 @@ GIT_EXTERN(int) git_diff_patch_num_lines_in_hunk(
  * @param new_lineno Line number in new file or -1 if line is deleted
  * @param patch The patch to look in
  * @param hunk_idx The index of the hunk
- * @param line_of_index The index of the line in the hunk
+ * @param line_of_hunk The index of the line in the hunk
  * @return 0 on success, <0 on failure
  */
 GIT_EXTERN(int) git_diff_patch_get_line_in_hunk(
@@ -1017,7 +1017,7 @@ GIT_EXTERN(int) git_diff_blobs(
  * @param old_as_path Treat old blob as if it had this filename; can be NULL
  * @param new_blob Blob for new side of diff, or NULL for empty blob
  * @param new_as_path Treat new blob as if it had this filename; can be NULL
- * @param options Options for diff, or NULL for default options
+ * @param opts Options for diff, or NULL for default options
  * @return 0 on success or error code < 0
  */
 GIT_EXTERN(int) git_diff_patch_from_blobs(
@@ -1048,7 +1048,7 @@ GIT_EXTERN(int) git_diff_patch_from_blobs(
  * @param options Options for diff, or NULL for default options
  * @param file_cb Callback for "file"; made once if there is a diff; can be NULL
  * @param hunk_cb Callback for each hunk in diff; can be NULL
- * @param line_cb Callback for each line in diff; can be NULL
+ * @param data_cb Callback for each line in diff; can be NULL
  * @param payload Payload passed to each callback function
  * @return 0 on success, GIT_EUSER on non-zero callback return, or error code
  */
@@ -1078,7 +1078,7 @@ GIT_EXTERN(int) git_diff_blob_to_buffer(
  * @param buffer Raw data for new side of diff, or NULL for empty
  * @param buffer_len Length of raw data for new side of diff
  * @param buffer_as_path Treat buffer as if it had this filename; can be NULL
- * @param options Options for diff, or NULL for default options
+ * @param opts Options for diff, or NULL for default options
  * @return 0 on success or error code < 0
  */
 GIT_EXTERN(int) git_diff_patch_from_blob_and_buffer(

include/git2/errors.h

@@ -100,7 +100,7 @@ GIT_EXTERN(void) giterr_clear(void);
  *
  * @param error_class One of the `git_error_t` enum above describing the
  *                    general subsystem that is responsible for the error.
- * @param message The formatted error message to keep
+ * @param string The formatted error message to keep
  */
 GIT_EXTERN(void) giterr_set_str(int error_class, const char *string);
 

include/git2/index.h

@@ -646,7 +646,7 @@ GIT_EXTERN(int) git_index_conflict_next(
 /**
  * Frees a `git_index_conflict_iterator`.
  *
- * @param it pointer to the iterator
+ * @param iterator pointer to the iterator
  */
 GIT_EXTERN(void) git_index_conflict_iterator_free(
 	git_index_conflict_iterator *iterator);

include/git2/indexer.h

@@ -21,7 +21,7 @@ typedef struct git_indexer_stream git_indexer_stream;
  * @param out where to store the indexer instance
  * @param path to the directory where the packfile should be stored
  * @param progress_cb function to call with progress information
- * @param progress_payload payload for the progress callback
+ * @param progress_cb_payload payload for the progress callback
  */
 GIT_EXTERN(int) git_indexer_stream_new(
 		git_indexer_stream **out,

include/git2/merge.h

@@ -141,7 +141,7 @@ GIT_EXTERN(int) git_merge_head_from_oid(
 /**
  * Frees a `git_merge_head`
  *
- * @param the merge head to free
+ * @param head merge head to free
  */
 GIT_EXTERN(void) git_merge_head_free(
 	git_merge_head *head);

include/git2/oid.h

@@ -85,7 +85,7 @@ GIT_EXTERN(void) git_oid_fromraw(git_oid *out, const unsigned char *raw);
  *		needed for an oid encoded in hex (40 bytes). Only the
  *		oid digits are written; a '\\0' terminator must be added
  *		by the caller if it is required.
- * @param oid oid structure to format.
+ * @param id oid structure to format.
  */
 GIT_EXTERN(void) git_oid_fmt(char *out, const git_oid *id);
 
@@ -96,7 +96,7 @@ GIT_EXTERN(void) git_oid_fmt(char *out, const git_oid *id);
  *		If the number of bytes is > GIT_OID_HEXSZ, extra bytes
  *		will be zeroed; if not, a '\0' terminator is NOT added.
  * @param n number of characters to write into out string
- * @param oid oid structure to format.
+ * @param id oid structure to format.
  */
 GIT_EXTERN(void) git_oid_nfmt(char *out, size_t n, const git_oid *id);
 
@@ -118,7 +118,7 @@ GIT_EXTERN(void) git_oid_pathfmt(char *out, const git_oid *id);
 /**
  * Format a git_oid into a newly allocated c-string.
  *
- * @param oid the oid structure to format
+ * @param id the oid structure to format
  * @return the c-string; NULL if memory is exhausted. Caller must
  *			deallocate the string with git__free().
  */

include/git2/pack.h

@@ -112,7 +112,7 @@ GIT_EXTERN(int) git_packbuilder_insert_commit(git_packbuilder *pb, const git_oid
  * @param pb The packbuilder
  * @param path to the directory where the packfile and index should be stored
  * @param progress_cb function to call with progress information from the indexer (optional)
- * @param progress_payload payload for the progress callback (optional)
+ * @param progress_cb_payload payload for the progress callback (optional)
  *
  * @return 0 or an error code
  */

include/git2/refs.h

@@ -62,7 +62,7 @@ GIT_EXTERN(int) git_reference_name_to_id(
  *
  * @param out pointer in which to store the reference
  * @param repo the repository in which to look
- * @param shrothand the short name for the reference
+ * @param shorthand the short name for the reference
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, const char *shorthand);
@@ -198,7 +198,7 @@ GIT_EXTERN(const char *) git_reference_name(const git_reference *ref);
  * If a direct reference is passed as an argument, a copy of that
  * reference is returned. This copy must be manually freed too.
  *
- * @param resolved_ref Pointer to the peeled reference
+ * @param out Pointer to the peeled reference
  * @param ref The reference
  * @return 0 or an error code
  */
@@ -266,7 +266,7 @@ GIT_EXTERN(int) git_reference_set_target(
  * the reflog if it exists.
  *
  * @param ref The reference to rename
- * @param name The new name for the reference
+ * @param new_name The new name for the reference
  * @param force Overwrite an existing reference
  * @return 0 on success, EINVALIDSPEC, EEXISTS or an error code
  *
@@ -375,7 +375,7 @@ GIT_EXTERN(int) git_reference_iterator_glob_new(
  *
  * @param out pointer in which to store the reference
  * @param iter the iterator
- * @param 0, GIT_ITEROVER if there are no more; or an error code
+ * @return 0, GIT_ITEROVER if there are no more; or an error code
  */
 GIT_EXTERN(int) git_reference_next(git_reference **out, git_reference_iterator *iter);
 
@@ -506,9 +506,9 @@ GIT_EXTERN(int) git_reference_normalize_name(
  * If you pass `GIT_OBJ_ANY` as the target type, then the object
  * will be peeled until a non-tag object is met.
  *
- * @param peeled Pointer to the peeled git_object
+ * @param out Pointer to the peeled git_object
  * @param ref The reference to be processed
- * @param target_type The type of the requested object (GIT_OBJ_COMMIT,
+ * @param type The type of the requested object (GIT_OBJ_COMMIT,
  * GIT_OBJ_TAG, GIT_OBJ_TREE, GIT_OBJ_BLOB or GIT_OBJ_ANY).
  * @return 0 on success, GIT_EAMBIGUOUS, GIT_ENOTFOUND or an error code
  */

include/git2/refspec.h

@@ -55,7 +55,7 @@ GIT_EXTERN(int) git_refspec_force(const git_refspec *refspec);
 /**
  * Get the refspec's direction.
  *
- * @param the refspec
+ * @param spec refspec
  * @return GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH
  */
 GIT_EXTERN(git_direction) git_refspec_direction(const git_refspec *spec);

include/git2/remote.h

@@ -259,7 +259,7 @@ GIT_EXTERN(int) git_remote_ls(git_remote *remote, git_headlist_cb list_cb, void
  * @param progress_cb function to call with progress information.  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
+ * @param payload payload for the progress callback
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_remote_download(
@@ -320,7 +320,7 @@ GIT_EXTERN(int) git_remote_update_tips(git_remote *remote);
  * Return whether a string is a valid remote URL
  *
  * @param url the url to check
- * @param 1 if the url is valid, 0 otherwise
+ * @return 1 if the url is valid, 0 otherwise
  */
 GIT_EXTERN(int) git_remote_valid_url(const char *url);
 

include/git2/repository.h

@@ -519,7 +519,7 @@ typedef int (*git_repository_mergehead_foreach_cb)(const git_oid *oid,
  *
  * @param repo A repository object
  * @param callback Callback function
- * @param apyload Pointer to callback data (optional)
+ * @param payload Pointer to callback data (optional)
  * @return 0 on success, GIT_ENOTFOUND, GIT_EUSER or error
  */
 GIT_EXTERN(int) git_repository_mergehead_foreach(git_repository *repo,

include/git2/stash.h

@@ -89,7 +89,7 @@ typedef int (*git_stash_cb)(
  *
  * @param repo Repository where to find the stash.
  *
- * @param callabck Callback to invoke per found stashed state. The most recent
+ * @param callback Callback to invoke per found stashed state. The most recent
  * stash state will be enumerated first.
  *
  * @param payload Extra parameter to callback function.

include/git2/submodule.h

@@ -481,7 +481,7 @@ GIT_EXTERN(int) git_submodule_sync(git_submodule *submodule);
  * function will return distinct `git_repository` objects.  This will only
  * work if the submodule is checked out into the working directory.
  *
- * @param subrepo Pointer to the submodule repo which was opened
+ * @param repo Pointer to the submodule repo which was opened
  * @param submodule Submodule to be opened
  * @return 0 on success, <0 if submodule repo could not be opened.
  */
@@ -531,7 +531,7 @@ GIT_EXTERN(int) git_submodule_status(
  * This can be useful if you want to know if the submodule is present in the
  * working directory at this point in time, etc.
  *
- * @param status Combination of first four `GIT_SUBMODULE_STATUS` flags
+ * @param location_status Combination of first four `GIT_SUBMODULE_STATUS` flags
  * @param submodule Submodule for which to get status
  * @return 0 on success, <0 on error
  */

include/git2/tree.h

@@ -38,7 +38,7 @@ GIT_EXTERN(int) git_tree_lookup(
  *
  * @see git_object_lookup_prefix
  *
- * @param tree pointer to the looked up tree
+ * @param out pointer to the looked up tree
  * @param repo the repo to use when locating the tree.
  * @param id identity of the tree to locate.
  * @param len the length of the short identifier
@@ -136,7 +136,7 @@ GIT_EXTERN(const git_tree_entry *) git_tree_entry_byoid(
  *
  * @param out Pointer where to store the tree entry
  * @param root Previously loaded tree which is the root of the relative path
- * @param subtree_path Path to the contained entry
+ * @param path Path to the contained entry
  * @return 0 on success; GIT_ENOTFOUND if the path does not exist
  */
 GIT_EXTERN(int) git_tree_entry_bypath(
@@ -212,7 +212,7 @@ GIT_EXTERN(int) git_tree_entry_cmp(const git_tree_entry *e1, const git_tree_entr
  *
  * You must call `git_object_free()` on the object when you are done with it.
  *
- * @param object pointer to the converted object
+ * @param object_out pointer to the converted object
  * @param repo repository where to lookup the pointed object
  * @param entry a tree entry
  * @return 0 or an error code
@@ -251,7 +251,7 @@ GIT_EXTERN(void) git_treebuilder_clear(git_treebuilder *bld);
 /**
  * Get the number of entries listed in a treebuilder
  *
- * @param tree a previously loaded treebuilder.
+ * @param bld a previously loaded treebuilder.
  * @return the number of entries in the treebuilder
  */
 GIT_EXTERN(unsigned int) git_treebuilder_entrycount(git_treebuilder *bld);