Merge pull request #2893 from phatblat/ben/pr/doc-comments

Fix doc comment formatting

include/git2/annotated_commit.h

@@ -44,7 +44,7 @@ GIT_EXTERN(int) git_annotated_commit_from_ref(
  * @param repo repository that contains the given commit
  * @param branch_name name of the (remote) branch
  * @param remote_url url of the remote
- * @param oid the commit object id of the remote branch
+ * @param id the commit object id of the remote branch
  * @return 0 on success or error code
  */
 GIT_EXTERN(int) git_annotated_commit_from_fetchhead(
@@ -80,7 +80,7 @@ GIT_EXTERN(int) git_annotated_commit_lookup(
 /**
  * Gets the commit ID that the given `git_annotated_commit` refers to.
  *
- * @param head the given annotated commit
+ * @param commit the given annotated commit
  * @return commit id
  */
 GIT_EXTERN(const git_oid *) git_annotated_commit_id(
@@ -89,7 +89,7 @@ GIT_EXTERN(const git_oid *) git_annotated_commit_id(
 /**
  * Frees a `git_annotated_commit`.
  *
- * @param annotated_commit annotated commit to free
+ * @param commit annotated commit to free
  */
 GIT_EXTERN(void) git_annotated_commit_free(
 	git_annotated_commit *commit);

include/git2/cherrypick.h

@@ -29,8 +29,8 @@ typedef struct {
 	/** For merge commits, the "mainline" is treated as the parent. */
 	unsigned int mainline;
 
-	git_merge_options merge_opts; /*< Options for the merging */
-	git_checkout_options checkout_opts; /*< Options for the checkout */
+	git_merge_options merge_opts; /**< Options for the merging */
+	git_checkout_options checkout_opts; /**< Options for the checkout */
 } git_cherrypick_options;
 
 #define GIT_CHERRYPICK_OPTIONS_VERSION 1

include/git2/config.h

@@ -59,9 +59,9 @@ typedef enum {
  * An entry in a configuration file
  */
 typedef struct {
-	const char *name; /*< Name of the entry (normalised) */
-	const char *value; /*< String value of the entry */
-	git_config_level_t level; /*< Which config file this was found in */
+	const char *name; /**< Name of the entry (normalised) */
+	const char *value; /**< String value of the entry */
+	git_config_level_t level; /**< Which config file this was found in */
 } git_config_entry;
 
 typedef int  (*git_config_foreach_cb)(const git_config_entry *, void *);
@@ -333,7 +333,7 @@ GIT_EXTERN(int) git_config_get_bool(int *out, const git_config *cfg, const char
  * @param out the buffer in which to store the result
  * @param cfg where to look for the variable
  * @param name the variable's name
- * @param 0 or an error code
+ * @return 0 or an error code
  */
 GIT_EXTERN(int) git_config_get_path(git_buf *out, const git_config *cfg, const char *name);
 

include/git2/describe.h

@@ -129,7 +129,7 @@ GIT_EXTERN(int) git_describe_commit(
  * worktree. After peforming describe on HEAD, a status is run and the
  * description is considered to be dirty if there are.
  *
- * @param result pointer to store the result. You must free this once
+ * @param out pointer to store the result. You must free this once
  * you're done with it.
  * @param repo the repository in which to perform the describe
  * @param opts the lookup options
@@ -142,9 +142,10 @@ GIT_EXTERN(int) git_describe_workdir(
 /**
  * Print the describe result to a buffer
  *
+ * @param out The buffer to store the result
  * @param result the result from `git_describe_commit()` or
  * `git_describe_workdir()`.
- * @param opt the formatting options
+ * @param opts the formatting options
  */
 GIT_EXTERN(int) git_describe_format(
 	git_buf *out,

include/git2/oid.h

@@ -123,7 +123,7 @@ GIT_EXTERN(void) git_oid_pathfmt(char *out, const git_oid *id);
  * will be stored in TLS (i.e. one buffer per thread) to allow for
  * concurrent calls of the function.
  *
- * @param id the oid structure to format
+ * @param oid The oid structure to format
  * @return the c-string
  */
 GIT_EXTERN(char *) git_oid_tostr_s(const git_oid *oid);

include/git2/rebase.h

@@ -156,7 +156,7 @@ GIT_EXTERN(int) git_rebase_init(
  * invocation of `git_rebase_init` or by another client.
  *
  * @param out Pointer to store the rebase object
- * @param reop The repository that has a rebase in-progress
+ * @param repo The repository that has a rebase in-progress
  * @return Zero on success; -1 on failure.
  */
 GIT_EXTERN(int) git_rebase_open(git_rebase **out, git_repository *repo);
@@ -195,8 +195,8 @@ GIT_EXTERN(git_rebase_operation *) git_rebase_operation_byindex(
  * working directory will be updated with the changes.  If there are conflicts,
  * you will need to address those before committing the changes.
  *
- * @param out Pointer to store the rebase operation that is to be performed next
- * @param repo The rebase in progress
+ * @param operation Pointer to store the rebase operation that is to be performed next
+ * @param rebase The rebase in progress
  * @param checkout_opts Options to specify how the patch should be checked out
  * @return Zero on success; -1 on failure.
  */
@@ -211,7 +211,7 @@ GIT_EXTERN(int) git_rebase_next(
  * invocation.
  *
  * @param id Pointer in which to store the OID of the newly created commit
- * @param repo The rebase that is in-progress
+ * @param rebase The rebase that is in-progress
  * @param author The author of the updated commit, or NULL to keep the
  *        author from the original commit
  * @param committer The committer of the rebase
@@ -255,7 +255,7 @@ GIT_EXTERN(int) git_rebase_abort(
  * @param rebase The rebase that is in-progress
  * @param signature The identity that is finishing the rebase (optional)
  * @param opts Options to specify how rebase is finished
- * @param Zero on success; -1 on error
+ * @return Zero on success; -1 on error
  */
 GIT_EXTERN(int) git_rebase_finish(
 	git_rebase *rebase,

include/git2/revert.h

@@ -29,8 +29,8 @@ typedef struct {
 	/** For merge commits, the "mainline" is treated as the parent. */
 	unsigned int mainline;
 
-	git_merge_options merge_opts; /*< Options for the merging */
-	git_checkout_options checkout_opts; /*< Options for the checkout */
+	git_merge_options merge_opts; /**< Options for the merging */
+	git_checkout_options checkout_opts; /**< Options for the checkout */
 } git_revert_options;
 
 #define GIT_REVERT_OPTIONS_VERSION 1

include/git2/transport.h

@@ -292,7 +292,7 @@ GIT_EXTERN(int) git_cred_username_new(git_cred **cred, const char *username);
  *
  * - cred: The newly created credential object.
  * - url: The resource for which we are demanding a credential.
- * - username_from_url: The username that was embedded in a "user@host"
+ * - username_from_url: The username that was embedded in a "user\@host"
  *                          remote url, or NULL if not included.
  * - allowed_types: A bitmask stating which cred types are OK to return.
  * - payload: The payload provided when specifying this callback.

include/git2/types.h

@@ -302,9 +302,7 @@ typedef struct {
 /**
  * Callback for the user's custom certificate checks.
  *
- * @param type The type of certificate or host info, SSH or X.509
- * @param data The data for the certificate or host info
- * @param len The size of the certificate or host info
+ * @param cert The host certificate
  * @param valid Whether the libgit2 checks (OpenSSL or WinHTTP) think
  * this certificate is valid
  * @param host Hostname of the host libgit2 connected to