From e1967164574816b8bf6740ea17d08eeb26c091d2 Mon Sep 17 00:00:00 2001 From: Andreas Linde Date: Mon, 24 Jun 2013 15:33:41 +0200 Subject: [PATCH] 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 | 2 +- include/git2/commit.h | 2 +- include/git2/config.h | 6 +++--- include/git2/diff.h | 10 +++++----- include/git2/errors.h | 2 +- include/git2/index.h | 2 +- include/git2/indexer.h | 2 +- include/git2/merge.h | 2 +- include/git2/oid.h | 6 +++--- include/git2/pack.h | 2 +- include/git2/refs.h | 12 ++++++------ include/git2/refspec.h | 2 +- include/git2/remote.h | 4 ++-- include/git2/repository.h | 2 +- include/git2/stash.h | 2 +- include/git2/submodule.h | 4 ++-- include/git2/tree.h | 8 ++++---- 17 files changed, 35 insertions(+), 35 deletions(-) diff --git a/include/git2/attr.h b/include/git2/attr.h index 0d8a910f2..f256ff861 100644 --- a/include/git2/attr.h +++ b/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 diff --git a/include/git2/commit.h b/include/git2/commit.h index 20b345f84..544d21d87 100644 --- a/include/git2/commit.h +++ b/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`. diff --git a/include/git2/config.h b/include/git2/config.h index 59b4307be..827d43544 100644 --- a/include/git2/config.h +++ b/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); diff --git a/include/git2/diff.h b/include/git2/diff.h index f352f2843..43029c49c 100644 --- a/include/git2/diff.h +++ b/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( diff --git a/include/git2/errors.h b/include/git2/errors.h index caf9e62b8..2032a436a 100644 --- a/include/git2/errors.h +++ b/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); diff --git a/include/git2/index.h b/include/git2/index.h index 399d7c9a8..51694aded 100644 --- a/include/git2/index.h +++ b/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); diff --git a/include/git2/indexer.h b/include/git2/indexer.h index 262dcd154..4db072c9b 100644 --- a/include/git2/indexer.h +++ b/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, diff --git a/include/git2/merge.h b/include/git2/merge.h index ce3ed8ed2..cef6f775b 100644 --- a/include/git2/merge.h +++ b/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); diff --git a/include/git2/oid.h b/include/git2/oid.h index 018cead4a..662338d93 100644 --- a/include/git2/oid.h +++ b/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(). */ diff --git a/include/git2/pack.h b/include/git2/pack.h index 242bddd25..cc1f48add 100644 --- a/include/git2/pack.h +++ b/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 */ diff --git a/include/git2/refs.h b/include/git2/refs.h index 1b6184be5..795f7ab27 100644 --- a/include/git2/refs.h +++ b/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 */ diff --git a/include/git2/refspec.h b/include/git2/refspec.h index c0b410cbf..d96b83ce2 100644 --- a/include/git2/refspec.h +++ b/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); diff --git a/include/git2/remote.h b/include/git2/remote.h index 3f43916b5..45d15d0a3 100644 --- a/include/git2/remote.h +++ b/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); diff --git a/include/git2/repository.h b/include/git2/repository.h index 4fbd913b1..2164cfac1 100644 --- a/include/git2/repository.h +++ b/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, diff --git a/include/git2/stash.h b/include/git2/stash.h index cf8bc9d4c..68d1b5413 100644 --- a/include/git2/stash.h +++ b/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. diff --git a/include/git2/submodule.h b/include/git2/submodule.h index 004665050..91b5300ae 100644 --- a/include/git2/submodule.h +++ b/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 */ diff --git a/include/git2/tree.h b/include/git2/tree.h index d673f50c4..65d8cc16e 100644 --- a/include/git2/tree.h +++ b/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);