From 41808d04705644b8af566c9039a3ddcbb3257c99 Mon Sep 17 00:00:00 2001 From: Ben Chatelain Date: Mon, 27 Jul 2015 14:46:50 -0600 Subject: [PATCH 1/5] Fix @param names in doc comments --- include/git2/repository.h | 2 +- include/git2/sys/odb_backend.h | 2 +- include/git2/sys/refdb_backend.h | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/include/git2/repository.h b/include/git2/repository.h index ce56fef0f..cf268ef85 100644 --- a/include/git2/repository.h +++ b/include/git2/repository.h @@ -745,7 +745,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 name the email to use for the reflog entries + * @param email the email to use for the reflog entries */ GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name, const char *email); diff --git a/include/git2/sys/odb_backend.h b/include/git2/sys/odb_backend.h index 0a51c6dba..fe102ff3c 100644 --- a/include/git2/sys/odb_backend.h +++ b/include/git2/sys/odb_backend.h @@ -93,7 +93,7 @@ struct git_odb_backend { * Initializes a `git_odb_backend` with default values. Equivalent to * creating an instance with GIT_ODB_BACKEND_INIT. * - * @param opts the `git_odb_backend` struct to initialize. + * @param backend the `git_odb_backend` struct to initialize. * @param version Version the struct; pass `GIT_ODB_BACKEND_VERSION` * @return Zero on success; -1 on failure. */ diff --git a/include/git2/sys/refdb_backend.h b/include/git2/sys/refdb_backend.h index d943e550f..8b004a7e0 100644 --- a/include/git2/sys/refdb_backend.h +++ b/include/git2/sys/refdb_backend.h @@ -175,7 +175,7 @@ struct git_refdb_backend { * Initializes a `git_refdb_backend` with default values. Equivalent to * creating an instance with GIT_REFDB_BACKEND_INIT. * - * @param opts the `git_refdb_backend` struct to initialize + * @param backend the `git_refdb_backend` struct to initialize * @param version Version of struct; pass `GIT_REFDB_BACKEND_VERSION` * @return Zero on success; -1 on failure. */ From f90fbb8d22c77fbc4d207ef68a9fd445e68602db Mon Sep 17 00:00:00 2001 From: Ben Chatelain Date: Mon, 27 Jul 2015 17:42:08 -0600 Subject: [PATCH 2/5] Use correct Doxygen trailing comment syntax --- include/git2/sys/diff.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/include/git2/sys/diff.h b/include/git2/sys/diff.h index 034d5c478..aa6fed757 100644 --- a/include/git2/sys/diff.h +++ b/include/git2/sys/diff.h @@ -38,7 +38,7 @@ GIT_EXTERN(int) git_diff_print_callback__to_buf( const git_diff_delta *delta, const git_diff_hunk *hunk, const git_diff_line *line, - void *payload); /*< payload must be a `git_buf *` */ + void *payload); /**< payload must be a `git_buf *` */ /** * Diff print callback that writes to stdio FILE handle. @@ -58,7 +58,7 @@ GIT_EXTERN(int) git_diff_print_callback__to_file_handle( const git_diff_delta *delta, const git_diff_hunk *hunk, const git_diff_line *line, - void *payload); /*< payload must be a `FILE *` */ + void *payload); /**< payload must be a `FILE *` */ /** @@ -66,8 +66,8 @@ GIT_EXTERN(int) git_diff_print_callback__to_file_handle( */ typedef struct { unsigned int version; - size_t stat_calls; /*< Number of stat() calls performed */ - size_t oid_calculations; /*< Number of ID calculations */ + size_t stat_calls; /**< Number of stat() calls performed */ + size_t oid_calculations; /** Date: Mon, 27 Jul 2015 18:28:29 -0600 Subject: [PATCH 3/5] Add -Wdocumentation flag if supported --- CMakeLists.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index 20e3272f9..a15ce7dbd 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -413,6 +413,7 @@ ELSE () SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fPIC") ENDIF () + ADD_C_FLAG_IF_SUPPORTED(-Wdocumentation) ADD_C_FLAG_IF_SUPPORTED(-Wno-missing-field-initializers) ADD_C_FLAG_IF_SUPPORTED(-Wstrict-aliasing=2) ADD_C_FLAG_IF_SUPPORTED(-Wstrict-prototypes) From 08afd227dfd3ee56accd6d6ded3889f34c5329fc Mon Sep 17 00:00:00 2001 From: Ben Chatelain Date: Mon, 27 Jul 2015 18:32:55 -0600 Subject: [PATCH 4/5] Fix remaining documentation warnings --- include/git2/sys/config.h | 2 +- include/git2/sys/diff.h | 2 +- src/path.h | 2 +- src/push.h | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/include/git2/sys/config.h b/include/git2/sys/config.h index b5b7df15f..044e34417 100644 --- a/include/git2/sys/config.h +++ b/include/git2/sys/config.h @@ -76,7 +76,7 @@ struct git_config_backend { * Initializes a `git_config_backend` with default values. Equivalent to * creating an instance with GIT_CONFIG_BACKEND_INIT. * - * @param opts the `git_config_backend` struct to initialize. + * @param backend the `git_config_backend` struct to initialize. * @param version Version of struct; pass `GIT_CONFIG_BACKEND_VERSION` * @return Zero on success; -1 on failure. */ diff --git a/include/git2/sys/diff.h b/include/git2/sys/diff.h index aa6fed757..aefd7b997 100644 --- a/include/git2/sys/diff.h +++ b/include/git2/sys/diff.h @@ -67,7 +67,7 @@ GIT_EXTERN(int) git_diff_print_callback__to_file_handle( typedef struct { unsigned int version; size_t stat_calls; /**< Number of stat() calls performed */ - size_t oid_calculations; /** Date: Tue, 28 Jul 2015 08:28:33 -0600 Subject: [PATCH 5/5] Better param docs --- src/push.h | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/push.h b/src/push.h index 53890f54b..a847ee0d0 100644 --- a/src/push.h +++ b/src/push.h @@ -83,7 +83,7 @@ int git_push_add_refspec(git_push *push, const char *refspec); * Update remote tips after a push * * @param push The push object - * @param callbacks The identity to use when updating reflogs + * @param callbacks the callbacks to use for this connection * * @return 0 or an error code */ @@ -100,6 +100,7 @@ int git_push_update_tips(git_push *push, const git_remote_callbacks *callbacks); * order to find out which updates were accepted or rejected. * * @param push The push object + * @param callbacks the callbacks to use for this connection * * @return 0 or an error code */ @@ -117,6 +118,7 @@ int git_push_finish(git_push *push, const git_remote_callbacks *callbacks); * * @param push The push object * @param cb The callback to call on each object + * @param data The payload passed to the callback * * @return 0 on success, non-zero callback return value, or error code */