From 15bc915d7469233eeed997044f79bd619b62bd4e Mon Sep 17 00:00:00 2001
From: Chengwei Yang <chengwei.yang@intel.com>
Date: Thu, 20 Jun 2013 22:03:49 +0800
Subject: [PATCH] Doc: fix incorrect param names, missing params, non-exist
 params

Signed-off-by: Chengwei Yang <chengwei.yang@intel.com>
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=65755
---
 dbus/dbus-connection.c         | 7 ++++---
 dbus/dbus-keyring.c            | 6 +++---
 dbus/dbus-marshal-header.c     | 4 +++-
 dbus/dbus-message.c            | 9 ++++-----
 dbus/dbus-object-tree.c        | 1 +
 dbus/dbus-syntax.c             | 8 ++++----
 dbus/dbus-sysdeps-unix.c       | 3 +++
 dbus/dbus-sysdeps-util-unix.c  | 2 --
 dbus/dbus-sysdeps-util-win.c   | 4 +---
 dbus/dbus-sysdeps-win.c        | 8 ++++----
 dbus/dbus-sysdeps-wince-glue.c | 2 +-
 dbus/dbus-test.c               | 1 +
 dbus/dbus-transport-socket.c   | 2 +-
 dbus/dbus-transport.c          | 2 ++
 14 files changed, 32 insertions(+), 27 deletions(-)

diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c
index 86adaa5..a471ea6 100644
--- a/dbus/dbus-connection.c
+++ b/dbus/dbus-connection.c
@@ -5230,7 +5230,8 @@ dbus_connection_get_unix_process_id (DBusConnection *connection,
  * connection.
  *
  * @param connection the connection
- * @param data return location for audit data 
+ * @param data return location for audit data
+ * @param data_size return location for length of audit data
  * @returns #TRUE if audit data is filled in with a valid ucred pointer
  */
 dbus_bool_t
@@ -6068,7 +6069,7 @@ dbus_connection_get_max_message_size (DBusConnection *connection)
  * result in disconnecting the connection.
  *
  * @param connection a #DBusConnection
- * @param size maximum message unix fds the connection can receive
+ * @param n maximum message unix fds the connection can receive
  */
 void
 dbus_connection_set_max_message_unix_fds (DBusConnection *connection,
@@ -6166,7 +6167,7 @@ dbus_connection_get_max_received_size (DBusConnection *connection)
  * The semantics are analogous to those of dbus_connection_set_max_received_size().
  *
  * @param connection the connection
- * @param size the maximum size in bytes of all outstanding messages
+ * @param n the maximum size in bytes of all outstanding messages
  */
 void
 dbus_connection_set_max_received_unix_fds (DBusConnection *connection,
diff --git a/dbus/dbus-keyring.c b/dbus/dbus-keyring.c
index 0e433a8..f0c64de 100644
--- a/dbus/dbus-keyring.c
+++ b/dbus/dbus-keyring.c
@@ -697,10 +697,10 @@ _dbus_keyring_unref (DBusKeyring *keyring)
 
 /**
  * Creates a new keyring that lives in the ~/.dbus-keyrings directory
- * of the given user credentials. If the credentials are #NULL or
- * empty, uses those of the current process.
+ * of the user represented by @p credentials. If the @p credentials are
+ * #NULL or empty, uses those of the current process.
  *
- * @param username username to get keyring for, or #NULL
+ * @param credentials a set of credentials representing a user or #NULL
  * @param context which keyring to get
  * @param error return location for errors
  * @returns the keyring or #NULL on error
diff --git a/dbus/dbus-marshal-header.c b/dbus/dbus-marshal-header.c
index 88887a8..48151c6 100644
--- a/dbus/dbus-marshal-header.c
+++ b/dbus/dbus-marshal-header.c
@@ -276,6 +276,7 @@ _dbus_header_cache_known_nonexistent (DBusHeader    *header,
  * Writes a struct of { byte, variant } with the given basic type.
  *
  * @param writer the writer (should be ready to write a struct)
+ * @param field the header field
  * @param type the type of the value
  * @param value the value as for _dbus_marshal_set_basic()
  * @returns #FALSE if no memory
@@ -336,6 +337,7 @@ write_basic_field (DBusTypeWriter *writer,
  * Sets a struct of { byte, variant } with the given basic type.
  *
  * @param reader the reader (should be iterating over the array pointing at the field to set)
+ * @param field the header field
  * @param type the type of the value
  * @param value the value as for _dbus_marshal_set_basic()
  * @param realign_root where to realign from
@@ -452,7 +454,6 @@ _dbus_header_reinit (DBusHeader *header)
  * to make the header valid, you have to call _dbus_header_create().
  *
  * @param header header to initialize
- * @param byte_order byte order of the header
  * @returns #FALSE if not enough memory
  */
 dbus_bool_t
@@ -514,6 +515,7 @@ _dbus_header_copy (const DBusHeader *header,
  * sense, and passing them in will trigger an assertion failure.
  *
  * @param header the header
+ * @param byte_order byte order of the header
  * @param message_type the message type
  * @param destination destination field or #NULL
  * @param path path field or #NULL
diff --git a/dbus/dbus-message.c b/dbus/dbus-message.c
index 079251e..20c8be3 100644
--- a/dbus/dbus-message.c
+++ b/dbus/dbus-message.c
@@ -3981,7 +3981,7 @@ _dbus_message_loader_get_unix_fds(DBusMessageLoader  *loader,
  *
  * @param loader the message loader.
  * @param fds the array fds were read into
- * @param max_n_fds how many fds were read
+ * @param n_fds how many fds were read
  */
 
 void
@@ -4409,7 +4409,7 @@ _dbus_message_loader_get_max_message_size (DBusMessageLoader  *loader)
  * Sets the maximum unix fds per message we allow.
  *
  * @param loader the loader
- * @param size the max number of unix fds in a message
+ * @param n the max number of unix fds in a message
  */
 void
 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader  *loader,
@@ -4729,9 +4729,8 @@ dbus_message_demarshal (const char *str,
  * Generally, this function is only useful for encapsulating D-Bus messages in
  * a different protocol.
  *
- * @param str data to be marshalled
- * @param len the length of str
- * @param error the location to save errors to
+ * @param buf data to be marshalled
+ * @param len the length of @p buf
  * @returns -1 if there was no valid data to be demarshalled, 0 if there wasn't enough data to determine how much should be demarshalled. Otherwise returns the number of bytes to be demarshalled
  * 
  */
diff --git a/dbus/dbus-object-tree.c b/dbus/dbus-object-tree.c
index 086fc64..f6ae19d 100644
--- a/dbus/dbus-object-tree.c
+++ b/dbus/dbus-object-tree.c
@@ -741,6 +741,7 @@ handle_default_introspect_and_unlock (DBusObjectTree          *tree,
  *
  * @param tree the global object tree
  * @param message the message to dispatch
+ * @param found_object return location for the object
  * @returns whether message was handled successfully
  */
 DBusHandlerResult
diff --git a/dbus/dbus-syntax.c b/dbus/dbus-syntax.c
index 4792287..7ef659c 100644
--- a/dbus/dbus-syntax.c
+++ b/dbus/dbus-syntax.c
@@ -93,7 +93,7 @@ dbus_validate_path (const char       *path,
  * is also checked, since it assumes that the string ends at the first zero
  * byte according to normal C conventions.
  *
- * @param path a potentially invalid interface name, which must not be #NULL
+ * @param name a potentially invalid interface name, which must not be #NULL
  * @param error error return
  * @returns #TRUE if name is valid
  */
@@ -140,7 +140,7 @@ dbus_validate_interface (const char       *name,
  * is also checked, since it assumes that the string ends at the first zero
  * byte according to normal C conventions.
  *
- * @param path a potentially invalid member name, which must not be #NULL
+ * @param name a potentially invalid member name, which must not be #NULL
  * @param error error return
  * @returns #TRUE if name is valid
  */
@@ -187,7 +187,7 @@ dbus_validate_member (const char       *name,
  * is also checked, since it assumes that the string ends at the first zero
  * byte according to normal C conventions.
  *
- * @param path a potentially invalid error name, which must not be #NULL
+ * @param name a potentially invalid error name, which must not be #NULL
  * @param error error return
  * @returns #TRUE if name is valid
  */
@@ -234,7 +234,7 @@ dbus_validate_error_name (const char       *name,
  * is also checked, since it assumes that the string ends at the first zero
  * byte according to normal C conventions.
  *
- * @param path a potentially invalid bus name, which must not be #NULL
+ * @param name a potentially invalid bus name, which must not be #NULL
  * @param error error return
  * @returns #TRUE if name is valid
  */
diff --git a/dbus/dbus-sysdeps-unix.c b/dbus/dbus-sysdeps-unix.c
index c2e6f9f..66f55d7 100644
--- a/dbus/dbus-sysdeps-unix.c
+++ b/dbus/dbus-sysdeps-unix.c
@@ -2929,6 +2929,7 @@ _dbus_close (int        fd,
  * (i.e. avoids stdin/stdout/stderr). Sets O_CLOEXEC.
  *
  * @param fd the file descriptor to duplicate
+ * @param error address of error location.
  * @returns duplicated file descriptor
  * */
 int
@@ -3441,6 +3442,7 @@ _read_subprocess_line_argv (const char *progpath,
  * address. If a failure happens, returns #FALSE and
  * sets an error in @p error.
  *
+ * @param scope scope of autolaunch (Windows only)
  * @param address a DBusString where the address can be stored
  * @param error a DBusError to store the error in case of failure
  * @returns #TRUE on success, #FALSE if an error happened
@@ -3569,6 +3571,7 @@ _dbus_read_local_machine_uuid (DBusGUID   *machine_id,
 
 /**
  * quries launchd for a specific env var which holds the socket path.
+ * @param socket_path append the socket path to this DBusString
  * @param launchd_env_var the env var to look up
  * @param error a DBusError to store the error in case of failure
  * @return the value of the env var
diff --git a/dbus/dbus-sysdeps-util-unix.c b/dbus/dbus-sysdeps-util-unix.c
index 6053265..9ad63b4 100644
--- a/dbus/dbus-sysdeps-util-unix.c
+++ b/dbus/dbus-sysdeps-util-unix.c
@@ -449,8 +449,6 @@ _dbus_init_system_log (dbus_bool_t is_daemon)
  *
  * @param severity a severity value
  * @param msg a printf-style format string
- * @param args arguments for the format string
- *
  */
 void
 _dbus_system_log (DBusSystemLogSeverity severity, const char *msg, ...)
diff --git a/dbus/dbus-sysdeps-util-win.c b/dbus/dbus-sysdeps-util-win.c
index abb10f7..71ed8b7 100644
--- a/dbus/dbus-sysdeps-util-win.c
+++ b/dbus/dbus-sysdeps-util-win.c
@@ -54,7 +54,7 @@
  * Does the chdir, fork, setsid, etc. to become a daemon process.
  *
  * @param pidfile #NULL, or pidfile to create
- * @param print_pid_fd file descriptor to print daemon's pid to, or -1 for none
+ * @param print_pid_pipe file descriptor to print daemon's pid to, or -1 for none
  * @param error return location for errors
  * @param keep_umask #TRUE to keep the original umask
  * @returns #FALSE on failure
@@ -272,8 +272,6 @@ _dbus_init_system_log (dbus_bool_t is_daemon)
  *
  * @param severity a severity value
  * @param msg a printf-style format string
- * @param args arguments for the format string
- *
  */
 void
 _dbus_system_log (DBusSystemLogSeverity severity, const char *msg, ...)
diff --git a/dbus/dbus-sysdeps-win.c b/dbus/dbus-sysdeps-win.c
index 20ecb4e..38758bd 100644
--- a/dbus/dbus-sysdeps-win.c
+++ b/dbus/dbus-sysdeps-win.c
@@ -522,7 +522,7 @@ _dbus_close_socket (int        fd,
  * on exec. Should be called for all file
  * descriptors in D-Bus code.
  *
- * @param fd the file descriptor
+ * @param handle the Windows HANDLE
  */
 void
 _dbus_fd_set_close_on_exec (intptr_t handle)
@@ -538,7 +538,7 @@ _dbus_fd_set_close_on_exec (intptr_t handle)
 /**
  * Sets a file descriptor to be nonblocking.
  *
- * @param fd the file descriptor.
+ * @param handle the file descriptor.
  * @param error address of error location.
  * @returns #TRUE on success.
  */
@@ -1909,7 +1909,7 @@ again:
  * The point of the byte is that on some systems we have to
  * use sendmsg()/recvmsg() to transmit credentials.
  *
- * @param client_fd the client file descriptor
+ * @param handle the client file descriptor
  * @param credentials struct to fill with credentials of client
  * @param error location to store error code
  * @returns #TRUE on success
@@ -3418,7 +3418,7 @@ _dbus_get_is_errno_eagain_or_ewouldblock (void)
 /**
  * return the absolute path of the dbus installation 
  *
- * @param s buffer for installation path
+ * @param prefix buffer for installation path
  * @param len length of buffer
  * @returns #FALSE on failure
  */
diff --git a/dbus/dbus-sysdeps-wince-glue.c b/dbus/dbus-sysdeps-wince-glue.c
index 74b1371..e276f04 100644
--- a/dbus/dbus-sysdeps-wince-glue.c
+++ b/dbus/dbus-sysdeps-wince-glue.c
@@ -491,7 +491,7 @@ SearchPathA (LPCSTR lpPath, LPCSTR lpFileName, LPCSTR lpExtension,
 
 
 /** Gets our SID
- * @param points to sid buffer, need to be freed with LocalFree()
+ * @param sid points to sid buffer, need to be freed with LocalFree()
  * @returns process sid
  */
 dbus_bool_t
diff --git a/dbus/dbus-test.c b/dbus/dbus-test.c
index 1539bce..b707ee2 100644
--- a/dbus/dbus-test.c
+++ b/dbus/dbus-test.c
@@ -94,6 +94,7 @@ run_data_test (const char             *test_name,
  * (with --enable-tests=no)
  *
  * @param test_data_dir the directory with test data (test/data normally)
+ * @param specific_test run specific test or #NULL to run all tests
  */
 void
 dbus_internal_do_not_use_run_tests (const char *test_data_dir, const char *specific_test)
diff --git a/dbus/dbus-transport-socket.c b/dbus/dbus-transport-socket.c
index 544d00a..acb91cf 100644
--- a/dbus/dbus-transport-socket.c
+++ b/dbus/dbus-transport-socket.c
@@ -1299,7 +1299,7 @@ _dbus_transport_new_for_socket (int               fd,
  * @param host the host to connect to
  * @param port the port to connect to
  * @param family the address family to connect to
- * @param path to nonce file
+ * @param noncefile path to nonce file
  * @param error location to store reason for failure.
  * @returns a new transport, or #NULL on failure.
  */
diff --git a/dbus/dbus-transport.c b/dbus/dbus-transport.c
index fff76cc..47437f2 100644
--- a/dbus/dbus-transport.c
+++ b/dbus/dbus-transport.c
@@ -242,6 +242,7 @@ _dbus_transport_finalize_base (DBusTransport *transport)
  * opened DBusTransport object. If it isn't, returns #NULL
  * and sets @p error.
  *
+ * @param address the address to be checked.
  * @param error address where an error can be returned.
  * @returns a new transport, or #NULL on failure.
  */
@@ -272,6 +273,7 @@ check_address (const char *address, DBusError *error)
  * Creates a new transport for the "autostart" method.
  * This creates a client-side of a transport.
  *
+ * @param scope scope of autolaunch (Windows only)
  * @param error address where an error can be returned.
  * @returns a new transport, or #NULL on failure.
  */
-- 
2.7.4