diff --git a/include/git2/remote.h b/include/git2/remote.h
index 33b7dfdec..d9ccdfda9 100644
--- a/include/git2/remote.h
+++ b/include/git2/remote.h
@@ -51,7 +51,7 @@ GIT_EXTERN(int) git_remote_new(git_remote **out, git_repository *repo, const cha
  * Get the information for a particular remote
  *
  * @param out pointer to the new remote object
- * @param cfg the repository's configuration
+ * @param repo the associated repository
  * @param name the remote's name
  * @return 0 or an error code
  */
@@ -168,8 +168,9 @@ GIT_EXTERN(int) git_remote_connect(git_remote *remote, int direction);
  * If you a return a non-zero value from the callback, this will stop
  * looping over the refs.
  *
- * @param refs where to store the refs
  * @param remote the remote
+ * @param list_cb function to call with each ref discovered at the remote
+ * @param payload additional data to pass to the callback
  * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_remote_ls(git_remote *remote, git_headlist_cb list_cb, void *payload);
@@ -201,6 +202,7 @@ GIT_EXTERN(int) git_remote_download(
  * Check whether the remote's underlying transport is connected to the
  * remote host.
  *
+ * @param remote the remote
  * @return 1 if it's connected, 0 otherwise.
  */
 GIT_EXTERN(int) git_remote_connected(git_remote *remote);
@@ -210,6 +212,8 @@ GIT_EXTERN(int) git_remote_connected(git_remote *remote);
  *
  * At certain points in its operation, the network code checks whether
  * the operation has been cancelled and if so stops the operation.
+ *
+ * @param remote the remote
  */
 GIT_EXTERN(void) git_remote_stop(git_remote *remote);
 
@@ -237,7 +241,7 @@ GIT_EXTERN(void) git_remote_free(git_remote *remote);
  * Update the tips to the new state
  *
  * @param remote the remote to update
- * @param cb callback to run on each ref update. 'a' is the old value, 'b' is then new value
+ * @return 0 or an error code
  */
 GIT_EXTERN(int) git_remote_update_tips(git_remote *remote);
 
@@ -275,6 +279,7 @@ GIT_EXTERN(int) git_remote_list(git_strarray *remotes_list, git_repository *repo
  * @param repo the repository in which to create the remote
  * @param name the remote's name
  * @param url the remote's url
+ * @return 0 or an error code
  */
 GIT_EXTERN(int) git_remote_add(git_remote **out, git_repository *repo, const char *name, const char *url);
 
@@ -293,7 +298,8 @@ GIT_EXTERN(void) git_remote_check_cert(git_remote *remote, int check);
  * failure so that retry can be performed.
  *
  * @param remote the remote to configure
- * @param The credentials acquisition callback to use (defaults to NULL)
+ * @param cred_acquire_cb The credentials acquisition callback to use (defaults
+ * to NULL)
  */
 GIT_EXTERN(void) git_remote_set_cred_acquire_cb(
 	git_remote *remote,
@@ -309,6 +315,7 @@ GIT_EXTERN(void) git_remote_set_cred_acquire_cb(
  *
  * @param remote the remote to configure
  * @param transport the transport object for the remote to use
+ * @return 0 or an error code
  */
 GIT_EXTERN(int) git_remote_set_transport(
 	git_remote *remote,