Cherry-pick PR #3332: Resolve documentation warnings

CMakeLists.txt

@@ -412,6 +412,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)

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);
 

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.
  */

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; /**< Number of ID calculations */
 } git_diff_perfdata;
 
 #define GIT_DIFF_PERFDATA_VERSION 1

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.
  */

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.
  */

src/path.h

@@ -319,7 +319,7 @@ extern int git_path_cmp(
  * @param callback Function to invoke on each path.  Passed the `payload`
  *		and the buffer containing the current path.  The path should not
  *		be modified in any way. Return non-zero to stop iteration.
- * @param state Passed to fn as the first ath.
+ * @param payload Passed to fn as the first ath.
  */
 extern int git_path_walk_up(
 	git_buf *pathbuf,

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 signature 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
  */