From 12a29ba2989d0497523ccfe55c5c12a1821ae4b9 Mon Sep 17 00:00:00 2001
From: Chengwei Yang <chengwei.yang@intel.com>
Date: Fri, 14 Jun 2013 21:52:56 +0800
Subject: [PATCH 2/2] Doc: fix incorrect param names, missing params,
 non-exist params

Signed-off-by: Chengwei Yang <chengwei.yang@intel.com>
---
 dbus/dbus-connection.c         |    5 +++--
 dbus/dbus-keyring.c            |    2 +-
 dbus/dbus-marshal-header.c     |    4 +++-
 dbus/dbus-message.c            |    7 +++----
 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, 28 insertions(+), 23 deletions(-)

diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c
index 0d017b3..c0068e4 100644
--- a/dbus/dbus-connection.c
+++ b/dbus/dbus-connection.c
@@ -5206,6 +5206,7 @@ dbus_connection_get_unix_process_id (DBusConnection *connection,
  *
  * @param connection the connection
  * @param data return location for audit data 
+ * @param data_size return length of audit data
  * @returns #TRUE if audit data is filled in with a valid ucred pointer
  */
 dbus_bool_t
@@ -6044,7 +6045,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,
@@ -6142,7 +6143,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 3b9ce31..c62530b 100644
--- a/dbus/dbus-keyring.c
+++ b/dbus/dbus-keyring.c
@@ -700,7 +700,7 @@ _dbus_keyring_unref (DBusKeyring *keyring)
  * of the given user credentials. If the credentials are #NULL or
  * empty, uses those of the current process.
  *
- * @param username username to get keyring for, or #NULL
+ * @param credentials username to get keyring for, 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 619bc69..aeeb45c 100644
--- a/dbus/dbus-message.c
+++ b/dbus/dbus-message.c
@@ -3968,7 +3968,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
@@ -4396,7 +4396,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,
@@ -4717,9 +4717,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 buf data to be marshalled
  * @param len the length of str
- * @param error the location to save errors to
  * @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 172c9d9..c09a0a6 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 found 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 4a586c7..8cbb835 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 return the socket path in 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 ab84967..6f062a2 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 72ccb93..60dd5c1 100644
--- a/dbus/dbus-sysdeps-win.c
+++ b/dbus/dbus-sysdeps-win.c
@@ -412,7 +412,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 file descriptor
  */
 void
 _dbus_fd_set_close_on_exec (intptr_t handle)
@@ -428,7 +428,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.
  */
@@ -1766,7 +1766,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
@@ -3275,7 +3275,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 224a6c8..7eaff3e 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 specific test
  */
 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 c483d76..f55c1da 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.
  */
-- 
1.7.9.5