Documentation: Fix many warnings from Doxygen.

* gio/src/gio_docs_override.xml:
* glib/src/glib_docs_override.xml: Move "Since: n.m" from the <return> to the
<description> entries. gmmproc adds a period at the end of the @return
Doxygen command, and Doxygen warns for "@newin{n,m}.".
* glib/glibmm/interface.h:
* glib/glibmm/stringutils.h:
* glib/glibmm/vectorutils.h:
* gio/src/*.hg:
* glib/src/*.hg: (Here "*" means "many", not "all") Examples of changes:
Add missing @param. Change names of parameters, to make them equal in
function declaration and @param command. Change "@name" to "@a name".
Change "<ulink url=" to "<a href=".

30 files changed, 177 insertions, 125 deletions

diff --git a/gio/src/appinfo.hg b/gio/src/appinfo.hg
index f5b5b536..77c80932 100644
--- a/gio/src/appinfo.hg
+++ b/gio/src/appinfo.hg
@@ -60,7 +60,7 @@ public:
                                                        const std::string& application_name,
                                                        AppInfoCreateFlags flags);
 
-  /**  Creates a duplicate of a this AppInfo.
+  /**  Creates a duplicate of this AppInfo.
    * @return A duplicate of this AppInfo.
    * @newin{2,36}
    */
@@ -68,6 +68,10 @@ public:
   _IGNORE(g_app_info_dup)
 
   // Note that the implementation of equal() is virtual via equal_vfunc().
+  /** Checks if two AppInfo<!-- -->s are equal.
+   * @param other The other AppInfo.
+   * @return <tt>true</tt> if @a *this is equal to @a other, <tt>false</tt> otherwise.
+   */
   _WRAP_METHOD(bool equal(const Glib::RefPtr<AppInfo>& other) const, g_app_info_equal)
 
   _WRAP_METHOD(std::string get_id() const, g_app_info_get_id)
@@ -98,15 +102,15 @@ public:
    * a textual uri you want to pass in as argument, consider using
    * launch_uris() instead.
    *
-   * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
+   * On UNIX, this function sets the @c GIO_LAUNCHED_DESKTOP_FILE
    * environment variable with the path of the launched desktop file and
-   * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process
+   * @c GIO_LAUNCHED_DESKTOP_FILE_PID to the process
    * id of the launched process. This can be used to ignore
-   * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited
-   * by further processes. The <envar>DISPLAY</envar> and
-   * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also
+   * @c GIO_LAUNCHED_DESKTOP_FILE, should it be inherited
+   * by further processes. The @c DISPLAY and
+   * @c DESKTOP_STARTUP_ID environment variables are also
    * set, based on information provided in @a launch_context.
-   * @param files A List of File objects.
+   * @param file A File object.
    * @param launch_context An AppLaunchContext.
    * @return <tt>true</tt> on successful launch, <tt>false</tt> otherwise.
    *
@@ -115,7 +119,7 @@ public:
   bool launch(const Glib::RefPtr<Gio::File>& file, const Glib::RefPtr<AppLaunchContext>& launch_context);
 
   /** Launches the application. This passes the @a file to the launched application
-   * as an arguments.
+   * as an argument.
    * On error, an exception will be thrown accordingly.
    *
    * Note that even if the launch is successful the application launched
@@ -127,15 +131,15 @@ public:
    * a textual uri you want to pass in as argument, consider using
    * launch_uris() instead.
    *
-   * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
+   * On UNIX, this function sets the @c GIO_LAUNCHED_DESKTOP_FILE
    * environment variable with the path of the launched desktop file and
-   * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process
+   * @c GIO_LAUNCHED_DESKTOP_FILE_PID to the process
    * id of the launched process. This can be used to ignore
-   * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited
-   * by further processes. The <envar>DISPLAY</envar> and
-   * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also
+   * @c GIO_LAUNCHED_DESKTOP_FILE, should it be inherited
+   * by further processes. The @c DISPLAY and
+   * @c DESKTOP_STARTUP_ID environment variables are also
    * set, based on information provided in @a launch_context.
-   * @param files A File object.
+   * @param file A File object.
    * @return <tt>true</tt> on successful launch, <tt>false</tt> otherwise.
    *
    * @newin{3,2}
@@ -215,7 +219,7 @@ public:
   _WRAP_METHOD(static Glib::RefPtr<AppInfo> get_default_for_type(const std::string& content_type, bool must_support_uris = true), g_app_info_get_default_for_type)
   _WRAP_METHOD(static Glib::RefPtr<AppInfo> get_default_for_uri_scheme(const std::string& uri_scheme), g_app_info_get_default_for_uri_scheme)
   _WRAP_METHOD(static void reset_type_associations(const std::string& content_type), g_app_info_reset_type_associations)
-  _WRAP_METHOD(static bool launch_default_for_uri(const std::string& uri, const Glib::RefPtr<AppLaunchContext>& context{?}), g_app_info_launch_default_for_uri, errthrow)
+  _WRAP_METHOD(static bool launch_default_for_uri(const std::string& uri, const Glib::RefPtr<AppLaunchContext>& launch_context{?}), g_app_info_launch_default_for_uri, errthrow)
 
 protected:
   //_WRAP_VFUNC(Glib::RefPtr<AppInfo> dup(), "dup")
diff --git a/gio/src/application.hg b/gio/src/application.hg
index d10f8a54..097dc38a 100644
--- a/gio/src/application.hg
+++ b/gio/src/application.hg
@@ -94,7 +94,7 @@ protected:
   /** Constructs an application instance.
    * If no application ID is given then some features (most notably application uniqueness) will be disabled.
    *
-   * @aparam application_id The application ID.
+   * @param application_id The application ID.
    * @param flags The application flags.
    */
   explicit Application(const Glib::ustring& application_id = Glib::ustring(), ApplicationFlags flags = APPLICATION_FLAGS_NONE);
@@ -104,7 +104,7 @@ public:
   /** Creates an application instance.
    * If no application ID is given then some features (most notably application uniqueness) will be disabled.
    *
-   * @aparam application_id The application ID.
+   * @param application_id The application ID.
    * @param flags The application flags.
    */
   _WRAP_CREATE(const Glib::ustring& application_id = Glib::ustring(), ApplicationFlags flags = APPLICATION_FLAGS_NONE)
diff --git a/gio/src/asyncinitable.hg b/gio/src/asyncinitable.hg
index c1d8e793..190fc5e4 100644
--- a/gio/src/asyncinitable.hg
+++ b/gio/src/asyncinitable.hg
@@ -98,7 +98,7 @@ protected:
   void init_async(const SlotAsyncReady& slot,
     int io_priority = Glib::PRIORITY_DEFAULT);
 
-  _WRAP_METHOD(bool init_finish(const Glib::RefPtr<AsyncResult>& result), g_async_initable_init_finish, errthrow)
+  _WRAP_METHOD(bool init_finish(const Glib::RefPtr<AsyncResult>& res), g_async_initable_init_finish, errthrow)
 
   _WRAP_METHOD(Glib::RefPtr<Glib::Object> create_finish(const Glib::RefPtr<AsyncResult>& res), g_async_initable_new_finish, errthrow)
 
diff --git a/gio/src/bufferedinputstream.hg b/gio/src/bufferedinputstream.hg
index d711fb56..d940f43b 100644
--- a/gio/src/bufferedinputstream.hg
+++ b/gio/src/bufferedinputstream.hg
@@ -62,7 +62,7 @@ public:
   /** Creates a new InputStream from the given base_stream, with a buffer set to size.
    *
    * @param base_stream An InputStream.
-   * @param size A size.
+   * @param buffer_size A size.
    * @result an InputStream for the given base_stream.
 	 */
   static Glib::RefPtr<BufferedInputStream> create_sized(const Glib::RefPtr<InputStream>& base_stream, gsize buffer_size);
diff --git a/gio/src/bufferedoutputstream.hg b/gio/src/bufferedoutputstream.hg
index 7d35ca9b..4933db9f 100644
--- a/gio/src/bufferedoutputstream.hg
+++ b/gio/src/bufferedoutputstream.hg
@@ -58,7 +58,7 @@ public:
   /** Creates a new buffered output stream with a given buffer size.
    *
    * @param base_stream An InputStream.
-   * @param size A size.
+   * @param buffer_size A size.
    * @result an OutputStream with an internal buffer set to size.
 	 */
   static Glib::RefPtr<BufferedOutputStream> create_sized(const Glib::RefPtr<OutputStream>& base_stream, gsize buffer_size);
diff --git a/gio/src/cancellable.ccg b/gio/src/cancellable.ccg
index 3c5d8eef..a266e7e5 100644
--- a/gio/src/cancellable.ccg
+++ b/gio/src/cancellable.ccg
@@ -41,9 +41,9 @@ void slot_cancelled_proxy(GCancellable * /*cancellable*/, gpointer data)
 } // extern "C"
 
 gulong
-Cancellable::connect(const SlotCancelledCallback& callback)
+Cancellable::connect(const SlotCancelledCallback& slot)
 {
-    SlotCancelledCallback* slot_copy = new SlotCancelledCallback(callback);
+    SlotCancelledCallback* slot_copy = new SlotCancelledCallback(slot);
     return g_cancellable_connect (gobj(),
                                   G_CALLBACK(slot_cancelled_proxy),
                                   slot_copy,
diff --git a/gio/src/cancellable.hg b/gio/src/cancellable.hg
index 33df9ce3..4ca5df55 100644
--- a/gio/src/cancellable.hg
+++ b/gio/src/cancellable.hg
@@ -67,9 +67,24 @@ public:
   // TODO: is this useful in the C++ API?
   //_WRAP_METHOD(void make_pollfd(PollFD* pollfd), g_cancellable_make_pollfd)
 
-  _WRAP_METHOD_DOCS_ONLY(g_cancellable_connect)
-  gulong connect(const SlotCancelledCallback& callback);
+  /** Convenience function to connect to the Cancellable::signal_cancelled()
+   * signal. Also handles the race condition that may happen
+   * if the cancellable is cancelled right before connecting.
+   * 
+   * @a slot is called at most once, either directly at the
+   * time of the connect if @a cancellable is already cancelled,
+   * or when @a cancellable is cancelled in some thread.
+   * 
+   * See Cancellable::signal_cancelled() for details on how to use this.
+   * 
+   * @newin{2,22}
+   * @param slot The slot to connect.
+   * @return The id of the signal handler or 0 if @a cancellable has already
+   * been cancelled.
+   */
+  gulong connect(const SlotCancelledCallback& slot);
   _IGNORE(g_cancellable_connect)
+
   _WRAP_METHOD(void disconnect(gulong handler_id), g_cancellable_disconnect)
 
   _WRAP_SIGNAL(void cancelled(), cancelled)
diff --git a/gio/src/charsetconverter.hg b/gio/src/charsetconverter.hg
index 331b9aa1..b4808c85 100644
--- a/gio/src/charsetconverter.hg
+++ b/gio/src/charsetconverter.hg
@@ -40,7 +40,13 @@ protected:
   _IGNORE(g_charset_converter_new)
 
 public:
-  _WRAP_METHOD_DOCS_ONLY(g_charset_converter_new)
+  /** Creates a new CharsetConverter.
+   * 
+   * @newin{2,24}
+   * @param to_charset Destination charset.
+   * @param from_charset Source charset.
+   * @return A new CharsetConverter, or <tt>0</tt> on error.
+   */
   _WRAP_CREATE(const Glib::ustring& to_charset, const Glib::ustring& from_charset)
 
   _WRAP_METHOD(void set_use_fallback(bool use_fallback), g_charset_converter_set_use_fallback)
diff --git a/gio/src/datainputstream.hg b/gio/src/datainputstream.hg
index 965d721d..6898fbfd 100644
--- a/gio/src/datainputstream.hg
+++ b/gio/src/datainputstream.hg
@@ -72,7 +72,7 @@ public:
    * another thread. If the operation
    * was cancelled, a Gio::Error with CANCELLED will be thrown.
    *
-   * @param data A string to fill with the read data (without the newlines).
+   * @param line A string to fill with the read data (without the newlines).
    * @param cancellable A cancellable object.
    * @result true if the read succeeded without error.
    */
@@ -81,7 +81,7 @@ public:
 
   /** A non-cancellable version of read_line().
    *
-   * @param data A string to fill with the read data (without the newlines).
+   * @param line A string to fill with the read data (without the newlines).
    * @result true if the read succeeded without error.
    */
   bool read_line(std::string& line);
@@ -147,8 +147,8 @@ public:
    * read_upto() instead, but note that that method
    * does not consume the stop character.
    *
-   * @param stop_chars Characters to terminate the read.
    * @param data A string to fill with the read data.
+   * @param stop_chars Characters to terminate the read.
    * @result true if the read succeeded without error.
    */
   bool read_until(std::string& data, const std::string& stop_chars);
@@ -191,7 +191,7 @@ public:
    * occurrence of any of the stop characters.
    *
    * In contrast to read_until(), this method
-   * does <emphasis>not</emphasis> consume the stop character. You have
+   * does <em>not</em> consume the stop character. You have
    * to use read_byte() to get it before calling
    * read_upto() again.
    *
@@ -204,8 +204,8 @@ public:
   _IGNORE(g_data_input_stream_read_upto)
 
   /** A non-cancellable version of read_upto().
-   * @param stop_chars Characters to terminate the read.
    * @param data A string to fill with the read data.
+   * @param stop_chars Characters to terminate the read.
    * @result true if the read succeeded without error.
    */
   bool read_upto(std::string& data, const std::string& stop_chars);
@@ -216,7 +216,7 @@ public:
    * an error to have two outstanding calls to this function.
    *
    * In contrast to read_until(), this method
-   * does <emphasis>not</emphasis> consume the stop character. You have
+   * does <em>not</em> consume the stop character. You have
    * to use read_byte() to get it before calling
    * read_upto() again.
    *
@@ -231,7 +231,7 @@ public:
 
   /** Finish an asynchronous call started by read_upto_async().
    *
-   * Note that this function does <emphasis>not</emphasis> consume the
+   * Note that this function does <em>not</em> consume the
    * stop character. You have to use read_byte() to
    * get it before calling read_upto_async() again.
    *
diff --git a/gio/src/dbusaddress.hg b/gio/src/dbusaddress.hg
index d552a740..ab5acd73 100644
--- a/gio/src/dbusaddress.hg
+++ b/gio/src/dbusaddress.hg
@@ -47,7 +47,7 @@ bool is_address(const std::string& string);
  * in @a address and that key/value pairs for each transport are valid.
  *
  * @param address A supposed address.
- * @return <tt>true</t> if @a address is a valid D-Bus address that is
+ * @return <tt>true</tt> if @a address is a valid D-Bus address that is
  * supported by this library, <tt>false</tt> otherwise.
  * @throw Glib::Error.
  * @newin{2,28}
@@ -110,10 +110,10 @@ Glib::RefPtr<IOStream> get_stream_finish(const Glib::RefPtr<AsyncResult>& res);
  * asynchronous version.
  *
  * @param address A valid D-Bus address.
+ * @param cancellable A Cancellable.
  * @param out_guid A return location to store the GUID extracted from address,
  * if any.
- * @param cancellable A Cancellable.
- * @param Returns A IOStream.
+ * @return A IOStream.
  * @throw Glib::Error.
  * @newin{2,28}
  * @ingroup DBus
@@ -134,7 +134,7 @@ Glib::RefPtr<IOStream> get_stream_sync(const std::string& address,
  *
  * @param address A valid D-Bus address.
  * @param cancellable A Cancellable.
- * @param Returns A IOStream.
+ * @return A IOStream.
  * @throw Glib::Error.
  * @newin{2,28}
  * @ingroup DBus
diff --git a/gio/src/dbusconnection.hg b/gio/src/dbusconnection.hg
index 5537e005..cde70db6 100644
--- a/gio/src/dbusconnection.hg
+++ b/gio/src/dbusconnection.hg
@@ -420,7 +420,7 @@ public:
   void close(const SlotAsyncReady& slot);
   _IGNORE(g_dbus_connection_close)
 
-  _WRAP_METHOD(bool close_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(bool close_finish(const Glib::RefPtr<AsyncResult>& res),
                g_dbus_connection_close_finish, errthrow)
 
   _WRAP_METHOD(void close_sync(const Glib::RefPtr<Cancellable>& cancellable{?}), g_dbus_connection_close_sync, errthrow)
@@ -477,7 +477,7 @@ public:
   void flush(const SlotAsyncReady& slot);
   _IGNORE(g_dbus_connection_flush)
 
-  _WRAP_METHOD(bool flush_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(bool flush_finish(const Glib::RefPtr<AsyncResult>& res),
                g_dbus_connection_flush_finish, errthrow)
 
   _WRAP_METHOD(void flush_sync(const Glib::RefPtr<Cancellable>& cancellable{?}), g_dbus_connection_flush_sync, errthrow)
@@ -537,7 +537,7 @@ public:
 
   _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_send_message_with_reply_finish)
   /// @throw Glib::Error.
-  _WRAP_METHOD(Glib::RefPtr<Message> send_message_with_reply_finish(const Glib::RefPtr<AsyncResult>& result), g_dbus_connection_send_message_with_reply_finish, errthrow)
+  _WRAP_METHOD(Glib::RefPtr<Message> send_message_with_reply_finish(const Glib::RefPtr<AsyncResult>& res), g_dbus_connection_send_message_with_reply_finish, errthrow)
 
   /** Synchronously sends @a message to the peer represented by the connection
    * and blocks the calling thread until a reply is received or the timeout is
@@ -780,7 +780,6 @@ public:
     int                                 timeout_msec = -1,
     CallFlags                           flags = Gio::DBus::CALL_FLAGS_NONE,
     const Glib::VariantType&            reply_type = Glib::VariantType());
-#endif // G_OS_LINUX
 
   /** Finishes an operation started with call() (with a UnixFDList).
    * @param res A AsyncResult obtained from the SlotAsyncReady passed to
@@ -790,6 +789,7 @@ public:
    * @newin{2,34}
    */
   _WRAP_METHOD(Glib::VariantContainerBase call_finish(const Glib::RefPtr<AsyncResult>& res{.}, Glib::RefPtr<UnixFDList>& out_fd_list{.>>}), g_dbus_connection_call_with_unix_fd_list_finish, errthrow, ifdef G_OS_LINUX)
+#endif // G_OS_LINUX
 
   _WRAP_METHOD(
     Glib::VariantContainerBase call_sync(
@@ -947,8 +947,8 @@ public:
   /** Registers exported objects at @a object_path with the D-Bus
    * interface that is described in @a interface_info. This method overload,
    * which does not take a VTable, is useful for
-   * <a href=="http://en.wikipedia.org/wiki/Marker_interface_pattern">marker
-   * interfaces</href>.
+   * <a href="http://en.wikipedia.org/wiki/Marker_interface_pattern">marker
+   * interfaces</a>.
    *
    * If an existing slot is already registered at @a object_path and @a
    * interface_name, then a Glib::Error is thrown.
diff --git a/gio/src/dbusproxy.hg b/gio/src/dbusproxy.hg
index cbf3d75c..1434431b 100644
--- a/gio/src/dbusproxy.hg
+++ b/gio/src/dbusproxy.hg
@@ -161,7 +161,7 @@ public:
 
   _WRAP_METHOD_DOCS_ONLY(g_dbus_proxy_new_finish)
   /// @throw Glib::Error.
-  _WRAP_METHOD(static Glib::RefPtr<Proxy> create_finish(const Glib::RefPtr<AsyncResult>& result), g_dbus_proxy_new_finish, errthrow)
+  _WRAP_METHOD(static Glib::RefPtr<Proxy> create_finish(const Glib::RefPtr<AsyncResult>& res), g_dbus_proxy_new_finish, errthrow)
 
   _WRAP_METHOD_DOCS_ONLY(g_dbus_proxy_new_sync)
   static Glib::RefPtr<Proxy>
@@ -203,7 +203,7 @@ public:
 
   _WRAP_METHOD_DOCS_ONLY(g_dbus_proxy_new_for_bus_finish)
   /// @throw Glib::Error.
-  _WRAP_METHOD(static Glib::RefPtr<Proxy> create_for_bus_finish(const Glib::RefPtr<AsyncResult>& result), g_dbus_proxy_new_for_bus_finish, errthrow)
+  _WRAP_METHOD(static Glib::RefPtr<Proxy> create_for_bus_finish(const Glib::RefPtr<AsyncResult>& res), g_dbus_proxy_new_for_bus_finish, errthrow)
 
   _WRAP_METHOD_DOCS_ONLY(g_dbus_proxy_new_for_bus_sync)
   static Glib::RefPtr<Proxy>
@@ -370,7 +370,6 @@ public:
     int                                 timeout_msec = -1,
     CallFlags                           flags = Gio::DBus::CALL_FLAGS_NONE,
     const Glib::VariantType&            reply_type = Glib::VariantType());
-#endif // G_OS_LINUX
 
   /** Finishes an operation started with call() (with a UnixFDList).
    * @param res A AsyncResult obtained from the SlotAsyncReady passed to
@@ -380,6 +379,7 @@ public:
    * @newin{2,34}
    */
   _WRAP_METHOD(Glib::VariantContainerBase call_finish(const Glib::RefPtr<AsyncResult>& res{.}, Glib::RefPtr<UnixFDList>& out_fd_list{.>>}), g_dbus_proxy_call_with_unix_fd_list_finish, errthrow, ifdef G_OS_LINUX)
+#endif // G_OS_LINUX
 
   _WRAP_METHOD(
     Glib::VariantContainerBase call_sync(
diff --git a/gio/src/dbuswatchname.hg b/gio/src/dbuswatchname.hg
index d3c2e350..ef555b7f 100644
--- a/gio/src/dbuswatchname.hg
+++ b/gio/src/dbuswatchname.hg
@@ -72,13 +72,13 @@ typedef sigc::slot<void, const Glib::RefPtr<Gio::DBus::Connection>&, Glib::ustri
  * application should create object proxies in @a name_appeared_slot and
  * destroy them again (if any) in @a name_vanished_slot.
  *
- * @param bus_type The type of bus to watch a name on.
- * @param name The name (well-known or unique) to watch.
- * @param name_appeared_slot Slot to invoke when name is known to exist.
- * @param name_vanished_slot Slot to invoke when name is known to not
+ * @param bus_type The type of bus to watch a name on.
+ * @param name The name (well-known or unique) to watch.
+ * @param name_appeared_slot Slot to invoke when name is known to exist.
+ * @param name_vanished_slot Slot to invoke when name is known to not
  * exist.
- * @param flags Flags from the BusNameWatcherFlags enumeration.
- * @return An identifier (never 0) that can be used with unwatch_name() to
+ * @param flags Flags from the BusNameWatcherFlags enumeration.
+ * @return An identifier (never 0) that can be used with unwatch_name() to
  * stop watching the name.
  *
  * @newin{2,28}
@@ -95,13 +95,13 @@ _IGNORE(g_bus_watch_name)
 
 /** A watch_name() function that takes a Connection instead of a BusType.
  *
- * @param connection A Connection.
- * @param name The name (well-known or unique) to watch.
- * @param name_appeared_slot Slot to invoke when name is known to exist.
- * @param name_vanished_slot Slot to invoke when name is known to not
+ * @param connection A Connection.
+ * @param name The name (well-known or unique) to watch.
+ * @param name_appeared_slot Slot to invoke when name is known to exist.
+ * @param name_vanished_slot Slot to invoke when name is known to not
  * exist.
- * @param flags Flags from the BusNameWatcherFlags enumeration.
- * @return An identifier (never 0) that can be used with unwatch_name() to
+ * @param flags Flags from the BusNameWatcherFlags enumeration.
+ * @return An identifier (never 0) that can be used with unwatch_name() to
  * stop watching the name.
  *
  * @newin{2,28}
diff --git a/gio/src/drive.hg b/gio/src/drive.hg
index b3406666..eaf48350 100644
--- a/gio/src/drive.hg
+++ b/gio/src/drive.hg
@@ -89,7 +89,6 @@ public:
   void eject(const Glib::RefPtr<MountOperation>& mount_operation, const SlotAsyncReady& slot, MountUnmountFlags flags = MOUNT_UNMOUNT_NONE);
 
   /** Ejects the drive.
-   * @param slot A callback which will be called when the eject is completed.
    * @param flags Flags affecting the unmount if required for eject.
    */
   void eject(MountUnmountFlags flags = MOUNT_UNMOUNT_NONE);
diff --git a/gio/src/emblemedicon.hg b/gio/src/emblemedicon.hg
index bfa3583f..66e79c68 100644
--- a/gio/src/emblemedicon.hg
+++ b/gio/src/emblemedicon.hg
@@ -47,9 +47,8 @@ class EmblemedIcon
 
 protected:
   //We have this constructor because g_emblemed_icon_new() may take a NULL emblem parameter.
- /** Creates a new emblemed icon for @a icon with the emblem @a emblem.
+  /** Creates a new emblemed icon for @a icon with no emblem.
    * @param icon An Icon.
-   * @param emblem An Emblem.
    *
    * @newin{2,28}
    */
diff --git a/gio/src/file.hg b/gio/src/file.hg
index 263d77fb..da5118cc 100644
--- a/gio/src/file.hg
+++ b/gio/src/file.hg
@@ -137,7 +137,18 @@ public:
   // (g_hash_table_new in C).
   _WRAP_METHOD(guint hash() const, g_file_hash)
 
-  //Not that the implementation of equal() is already virtual via equal_vfunc().
+  //Note that the implementation of equal() is already virtual via equal_vfunc().
+  /** Checks equality of two given Files.
+   * 
+   * Note that two Files that differ can still refer to the same
+   * file on the filesystem due to various forms of filename
+   * aliasing.
+   * 
+   * This call does no blocking I/O.
+   * @param other The other File.
+   * @return <tt>true</tt> if @a *this and @a other are equal.
+   * <tt>false</tt> if either is not a File.
+   */
   _WRAP_METHOD(bool equal(const Glib::RefPtr<const File>& other) const, g_file_equal)
 
   _WRAP_METHOD(std::string get_basename() const, g_file_get_basename)
@@ -463,7 +474,7 @@ public:
   void append_to_async(const SlotAsyncReady& slot, FileCreateFlags flags = FILE_CREATE_NONE, int io_priority = Glib::PRIORITY_DEFAULT);
   _IGNORE(g_file_append_to_async)
 
-  _WRAP_METHOD(Glib::RefPtr<FileOutputStream> append_to_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(Glib::RefPtr<FileOutputStream> append_to_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_append_to_finish,
                errthrow)
 
@@ -494,7 +505,7 @@ public:
   void create_file_async(const SlotAsyncReady& slot, FileCreateFlags flags = FILE_CREATE_NONE, int io_priority = Glib::PRIORITY_DEFAULT);
   _IGNORE(g_file_create_async)
 
-  _WRAP_METHOD(Glib::RefPtr<FileOutputStream> create_file_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(Glib::RefPtr<FileOutputStream> create_file_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_create_finish,
                errthrow)
 
@@ -531,7 +542,7 @@ public:
   void create_file_readwrite_async(const SlotAsyncReady& slot, FileCreateFlags flags = FILE_CREATE_NONE, int io_priority = Glib::PRIORITY_DEFAULT);
   _IGNORE(g_file_create_readwrite_async)
 
-  _WRAP_METHOD(Glib::RefPtr<FileIOStream> create_file_readwrite_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(Glib::RefPtr<FileIOStream> create_file_readwrite_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_create_readwrite_finish,
                errthrow)
 
@@ -561,7 +572,7 @@ public:
   void replace_async(const SlotAsyncReady& slot, const std::string& etag = std::string(), bool make_backup = false, FileCreateFlags flags = FILE_CREATE_NONE, int io_priority = Glib::PRIORITY_DEFAULT);
   _IGNORE(g_file_replace_async)
 
-  _WRAP_METHOD(Glib::RefPtr<FileOutputStream> replace_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(Glib::RefPtr<FileOutputStream> replace_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_replace_finish,
                errthrow)
 
@@ -611,7 +622,7 @@ public:
   void open_readwrite_async(const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT);
   _IGNORE(g_file_open_readwrite_async)
 
-  _WRAP_METHOD(Glib::RefPtr<FileIOStream> open_readwrite_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(Glib::RefPtr<FileIOStream> open_readwrite_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_open_readwrite_finish,
                errthrow)
 
@@ -625,6 +636,7 @@ public:
    * so make sure you really need to do read and write streaming,
    * rather than just opening for reading or writing.
    *
+   * @param cancellable A Cancellable object which can be used to cancel the operation.
    * @param etag An optional entity tag for the current Glib::File.
    * @param make_backup <tt>true</tt> if a backup should be created.
    * @param flags A set of FileCreateFlags.
@@ -690,7 +702,7 @@ public:
   void replace_readwrite_async(const SlotAsyncReady& slot, const std::string& etag = std::string(), bool make_backup = false, FileCreateFlags flags = FILE_CREATE_NONE, int io_priority = Glib::PRIORITY_DEFAULT);
   _IGNORE(g_file_replace_readwrite_async)
 
-  _WRAP_METHOD(Glib::RefPtr<FileIOStream> replace_readwrite_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(Glib::RefPtr<FileIOStream> replace_readwrite_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_replace_readwrite_finish,
                errthrow)
 
@@ -762,7 +774,7 @@ public:
   //We cannot use the {?} format here because we want a default value for flags, but gmmproc then generates a method with a default value for flags when it is not the last parameter.
   _WRAP_METHOD(FileType query_file_type(FileQueryInfoFlags flags, const Glib::RefPtr<Cancellable>& cancellable) const, g_file_query_file_type)
 
-  /** Utility function to inspect the #GFileType of a file. This is
+  /** Utility function to inspect the FileType of a file. This is
    * implemented using query_info() and as such does blocking I/O.
    *
    * The primary use case of this method is to check if a file is a regular file,
@@ -802,7 +814,7 @@ public:
   _IGNORE(g_file_query_info_async)
 
 
-  _WRAP_METHOD(Glib::RefPtr<FileInfo> query_info_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(Glib::RefPtr<FileInfo> query_info_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_query_info_finish,
                errthrow)
 
@@ -892,7 +904,7 @@ public:
   void query_filesystem_info_async(const SlotAsyncReady& slot, const std::string& attributes = "*", int io_priority = Glib::PRIORITY_DEFAULT) const;
   _IGNORE(g_file_query_filesystem_info_async)
 
-  _WRAP_METHOD(Glib::RefPtr<FileInfo> query_filesystem_info_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(Glib::RefPtr<FileInfo> query_filesystem_info_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_query_filesystem_info_finish,
                errthrow)
 
@@ -924,7 +936,7 @@ public:
   void find_enclosing_mount_async(const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT);
   _IGNORE(g_file_find_enclosing_mount_async)
 
-  _WRAP_METHOD(Glib::RefPtr<Mount> find_enclosing_mount_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(Glib::RefPtr<Mount> find_enclosing_mount_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_find_enclosing_mount_finish, errthrow)
 
   /** Gets the requested information about the files in a directory. The result
@@ -1006,7 +1018,7 @@ public:
   void enumerate_children_async(const SlotAsyncReady& slot, const std::string& attributes = "*", FileQueryInfoFlags flags = FILE_QUERY_INFO_NONE, int io_priority = Glib::PRIORITY_DEFAULT);
   _IGNORE(g_file_enumerate_children_async)
 
-  _WRAP_METHOD(Glib::RefPtr<FileEnumerator> enumerate_children_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(Glib::RefPtr<FileEnumerator> enumerate_children_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_enumerate_children_finish,
                errthrow)
 
@@ -1034,7 +1046,7 @@ public:
   void set_display_name_async(const Glib::ustring& display_name, const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT);
   _IGNORE(g_file_set_display_name_async)
 
-  _WRAP_METHOD(Glib::RefPtr<File> set_display_name_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(Glib::RefPtr<File> set_display_name_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_set_display_name_finish,
                errthrow)
 
@@ -1051,7 +1063,7 @@ public:
                 errthrow)
 
    /** Asynchronously delete a file.
-    * If the @file is a directory, it will
+    * If the file is a directory, it will
     * only be deleted if it is empty.  This has the same semantics as
     * g_unlink().
     *
@@ -1063,7 +1075,7 @@ public:
   void remove_async(const SlotAsyncReady& slot_ready, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = Glib::PRIORITY_DEFAULT);
 
    /** Asynchronously delete a file.
-    * If the @file is a directory, it will
+    * If the file is a directory, it will
     * only be deleted if it is empty.  This has the same semantics as
     * g_unlink().
     *
@@ -1215,7 +1227,7 @@ public:
   void copy_async(const Glib::RefPtr<File>& destination, const SlotAsyncReady& slot_ready, FileCopyFlags flags = FILE_COPY_NONE, int io_priority = Glib::PRIORITY_DEFAULT);
   _IGNORE(g_file_copy_async)
 
-  _WRAP_METHOD(bool copy_finish(const Glib::RefPtr<AsyncResult>& result),
+  _WRAP_METHOD(bool copy_finish(const Glib::RefPtr<AsyncResult>& res),
                g_file_copy_finish,
                errthrow)
 
@@ -1380,6 +1392,7 @@ public:
    * @param mount_operation A MountOperation.
    * @param slot A callback slot which will be called when the request is satisfied.
    * @param cancellable A Cancellable object.
+   * @param flags Flags affecting the operation.
    */
   void mount_enclosing_volume(const Glib::RefPtr<MountOperation>& mount_operation, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, MountMountFlags flags = MOUNT_MOUNT_NONE);
 
@@ -1390,6 +1403,7 @@ public:
    *
    * @param mount_operation A MountOperation.
    * @param slot A callback slot which will be called when the request is satisfied.
+   * @param flags Flags affecting the operation.
    */
   void mount_enclosing_volume(const Glib::RefPtr<MountOperation>& mount_operation, const SlotAsyncReady& slot, MountMountFlags flags = MOUNT_MOUNT_NONE);
 
@@ -1399,12 +1413,14 @@ public:
    * and the operation can be finalized with mount_enclosing_volume_finish().
    *
    * @param slot A callback slot which will be called when the request is satisfied.
+   * @param flags Flags affecting the operation.
    */
   void mount_enclosing_volume(const SlotAsyncReady& slot, MountMountFlags flags = MOUNT_MOUNT_NONE);
   _IGNORE(g_file_mount_enclosing_volume)
 
   /** Starts a @a mount_operation, mounting the volume that contains the file.
    *
+   * @param flags Flags affecting the operation.
    */
   void mount_enclosing_volume(MountMountFlags flags = MOUNT_MOUNT_NONE);
   _IGNORE(g_file_mount_enclosing _volume)
@@ -1424,6 +1440,7 @@ public:
    * @param mount_operation A MountOperation.
    * @param cancellable A Cancellable object which can be used to cancel the operation.
    * @param slot A callback slot which will be called when the request is satisfied.
+   * @param flags Flags affecting the operation.
    */
   void mount_mountable(const Glib::RefPtr<MountOperation>& mount_operation, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, MountMountFlags flags = MOUNT_MOUNT_NONE);
 
@@ -1434,6 +1451,7 @@ public:
    *
    * @param mount_operation A MountOperation.
    * @param slot A callback slot which will be called when the request is satisfied.
+   * @param flags Flags affecting the operation.
    */
   void mount_mountable(const Glib::RefPtr<MountOperation>& mount_operation, const SlotAsyncReady& slot, MountMountFlags flags = MOUNT_MOUNT_NONE);
 
@@ -1442,10 +1460,13 @@ public:
    * When the operation is finished, @a slot will be called. You can then call mount_mountable_finish() to get the result of the operation.
    *
    * @param slot A callback slot which will be called when the request is satisfied.
+   * @param flags Flags affecting the operation.
    */
   void mount_mountable(const SlotAsyncReady& slot, MountMountFlags flags = MOUNT_MOUNT_NONE);
 
   /** Mounts a file of type FILE_TYPE_MOUNTABLE without user interaction.
+   *
+   * @param flags Flags affecting the operation.
    */
   void mount_mountable(MountMountFlags flags = MOUNT_MOUNT_NONE);
   _IGNORE(g_file_mount_mountable)
@@ -1654,8 +1675,8 @@ public:
    * The operation can be cancelled by triggering the cancellable object from another thread. If the operation
    * was cancelled, a Gio::Error with CANCELLED will be thrown.
    *
+   * @param cancellable A Cancellable object.
    * @param flags A set of FileMonitorFlags.
-   * @param A Cancellable object.
    * @return A FileMonitor for the file.
    */
   Glib::RefPtr<FileMonitor> monitor_file(const Glib::RefPtr<Cancellable>& cancellable, FileMonitorFlags flags = FILE_MONITOR_NONE);
@@ -1667,7 +1688,6 @@ public:
    * was cancelled, a Gio::Error with CANCELLED will be thrown.
    *
    * @param flags A set of FileMonitorFlags.
-   * @param A Cancellable object.
    * @return A FileMonitor for the file.
    */
   Glib::RefPtr<FileMonitor> monitor_file(FileMonitorFlags flags = FILE_MONITOR_NONE);
@@ -1680,8 +1700,8 @@ public:
    * The operation can be cancelled by triggering the cancellable object from another thread. If the operation
    * was cancelled, a Gio::Error with CANCELLED will be thrown.
    *
+   * @param cancellable A Cancellable object.
    * @param flags A set of FileMonitorFlags.
-   * @param A Cancellable object.
    * @return A FileMonitor for the file.
    *
    * @newin{2,18}
@@ -1695,7 +1715,6 @@ public:
    * was cancelled, a Gio::Error with CANCELLED will be thrown.
    *
    * @param flags A set of FileMonitorFlags.
-   * @param A Cancellable object.
    * @return A FileMonitor for the file.
    *
    * @newin{2,18}
@@ -1716,8 +1735,9 @@ public:
   * triggering the cancellable object from another thread. If the operation
   * was cancelled, a Gio::Error with CANCELLED will be thrown.
   *
-  * @param slot: A callback to call when the request is satisfied.
+  * @param slot A callback to call when the request is satisfied.
   * @param cancellable A Cancellable object.
+  * @param start_operation A MountOperation, or <tt>0</tt> to avoid user interaction.
   * @param flags Flags affecting the operation
   *
   * @newin{2,24}
@@ -1735,8 +1755,8 @@ public:
   * triggering the cancellable object from another thread. If the operation
   * was cancelled, a Gio::Error with CANCELLED will be thrown.
   *
-  * @param slot: A callback to call when the request is satisfied.
-  * @param cancellable A Cancellable object.
+  * @param slot A callback to call when the request is satisfied.
+  * @param start_operation A MountOperation, or <tt>0</tt> to avoid user interaction.
   * @param flags Flags affecting the operation
   *
   * @newin{2,24}
@@ -1759,8 +1779,9 @@ public:
   * triggering the cancellable object from another thread. If the operation
   * was cancelled, a Gio::Error with CANCELLED will be thrown.
   *
-  * @param slot: A callback to call when the request is satisfied.
+  * @param slot A callback to call when the request is satisfied.
   * @param cancellable A Cancellable object.
+  * @param start_operation A MountOperation, or <tt>0</tt> to avoid user interaction.
   * @param flags Flags affecting the operation
   *
   * @newin{2,24}
@@ -1779,8 +1800,8 @@ public:
   * triggering the cancellable object from another thread. If the operation
   * was cancelled, a Gio::Error with CANCELLED will be thrown.
   *
-  * @param slot: A callback to call when the request is satisfied.
-  * @param start_operation A Cancellable object.
+  * @param slot A callback to call when the request is satisfied.
+  * @param start_operation A MountOperation, or <tt>0</tt> to avoid user interaction.
   * @param flags Flags affecting the operation
   *
   * @newin{2,24}
@@ -1912,7 +1933,7 @@ public:
    * The contents are placed in @a contents, and @a length is set to the
    * size of the @a contents string. If @a etag_out is present, it will be
    * set to the new entity tag for the @a file.
-   * @param res A AsyncResult.
+   * @param result A AsyncResult.
    * @param contents A location to place the contents of the file.
    * @param length A location to place the length of the contents of the file.
    * @param etag_out A location to place the current entity tag for the file.
@@ -1925,7 +1946,7 @@ public:
    * The contents are placed in @a contents, and @a length is set to the
    * size of the @a contents string. If @a etag_out is present, it will be
    * set to the new entity tag for the @a file.
-   * @param res A AsyncResult.
+   * @param result A AsyncResult.
    * @param contents A location to place the contents of the file.
    * @param length A location to place the length of the contents of the file.
    * @return <tt>true</tt> if the load was successful. If <tt>false</tt> and @a error is
@@ -1975,7 +1996,7 @@ public:
 
   /** Finishes an asynchronous partial load operation that was started
    * with load_partial_contents_async().
-   * @param res A AsyncResult.
+   * @param result A AsyncResult.
    * @param contents A location to place the contents of the file.
    * @param length A location to place the length of the contents of the file.
    * @param etag_out A location to place the current entity tag for the file.
@@ -1986,7 +2007,7 @@ public:
 
   /** Finishes an asynchronous partial load operation that was started
    * with load_partial_contents_async().
-   * @param res A AsyncResult.
+   * @param result A AsyncResult.
    * @param contents A location to place the contents of the file.
    * @param length A location to place the length of the contents of the file.
    * @return <tt>true</tt> if the load was successful. If <tt>false</tt> and @a error is
diff --git a/gio/src/fileinfo.hg b/gio/src/fileinfo.hg
index f587e8ed..de8a330b 100644
--- a/gio/src/fileinfo.hg
+++ b/gio/src/fileinfo.hg
@@ -65,8 +65,8 @@ public:
 
   _WRAP_METHOD(Glib::RefPtr<FileAttributeMatcher> create_difference(const Glib::RefPtr<const FileAttributeMatcher>& subtract) const, g_file_attribute_matcher_subtract)
 
-  _WRAP_METHOD(bool matches(const std::string& full_name) const, g_file_attribute_matcher_matches)
-  _WRAP_METHOD(bool matches_only(const std::string& full_name) const, g_file_attribute_matcher_matches_only)
+  _WRAP_METHOD(bool matches(const std::string& attribute) const, g_file_attribute_matcher_matches)
+  _WRAP_METHOD(bool matches_only(const std::string& attribute) const, g_file_attribute_matcher_matches_only)
   _WRAP_METHOD(bool enumerate_namespace(const std::string& ns), g_file_attribute_matcher_enumerate_namespace)
   _WRAP_METHOD(std::string enumerate_next(), g_file_attribute_matcher_enumerate_next)
   _WRAP_METHOD(std::string to_string() const, g_file_attribute_matcher_to_string)
@@ -90,7 +90,7 @@ public:
 
   _WRAP_METHOD(Glib::RefPtr<FileInfo> dup() const,
                g_file_info_dup)
-  _WRAP_METHOD(void copy_into(Glib::RefPtr<FileInfo>& dest) const,
+  _WRAP_METHOD(void copy_into(Glib::RefPtr<FileInfo>& dest_info) const,
                g_file_info_copy_into)
   _WRAP_METHOD(bool has_attribute(const std::string& attribute) const,
                g_file_info_has_attribute)
@@ -141,19 +141,19 @@ public:
 #m4 _CONVERSION(`const std::vector<Glib::ustring>&',`char**',`const_cast<char**>(Glib::ArrayHandler<Glib::ustring>::vector_to_array($3).data())')
   _WRAP_METHOD(void set_attribute_strings(const std::string& attribute, const std::vector<Glib::ustring>& attr_value), g_file_info_set_attribute_stringv)
 
-  _WRAP_METHOD(void set_attribute_byte_string(const std::string& attribute, const std::string& value),
+  _WRAP_METHOD(void set_attribute_byte_string(const std::string& attribute, const std::string& attr_value),
                g_file_info_set_attribute_byte_string)
-  _WRAP_METHOD(void set_attribute_boolean(const std::string& attribute, bool value),
+  _WRAP_METHOD(void set_attribute_boolean(const std::string& attribute, bool attr_value),
                g_file_info_set_attribute_boolean)
-  _WRAP_METHOD(void set_attribute_uint32(const std::string& attribute, guint32 value),
+  _WRAP_METHOD(void set_attribute_uint32(const std::string& attribute, guint32 attr_value),
                g_file_info_set_attribute_uint32)
-  _WRAP_METHOD(void set_attribute_int32(const std::string& attribute, gint32 value),
+  _WRAP_METHOD(void set_attribute_int32(const std::string& attribute, gint32 attr_value),
                g_file_info_set_attribute_int32)
-  _WRAP_METHOD(void set_attribute_uint64(const std::string& attribute, guint64 value),
+  _WRAP_METHOD(void set_attribute_uint64(const std::string& attribute, guint64 attr_value),
                g_file_info_set_attribute_uint64)
-  _WRAP_METHOD(void set_attribute_int64(const std::string& attribute, gint64 value),
+  _WRAP_METHOD(void set_attribute_int64(const std::string& attribute, gint64 attr_value),
                g_file_info_set_attribute_int64)
-  _WRAP_METHOD(void set_attribute_object(const std::string& attribute, const Glib::RefPtr<Glib::Object>& object),
+  _WRAP_METHOD(void set_attribute_object(const std::string& attribute, const Glib::RefPtr<Glib::Object>& attr_value),
                g_file_info_set_attribute_object)
   _WRAP_METHOD(void clear_status(), g_file_info_clear_status)
 
diff --git a/gio/src/fileoutputstream.hg b/gio/src/fileoutputstream.hg
index 0ba250a4..4b24272f 100644
--- a/gio/src/fileoutputstream.hg
+++ b/gio/src/fileoutputstream.hg
@@ -91,7 +91,6 @@ public:
    * was cancelled, a Gio::Error with CANCELLED may be thrown, and an empty RefPtr will
    * be returned.
    *
-   * @param cancellable A Cancellable object.
    * @param attributes A file attribute query string.
    * @return A FileInfo for the stream, or an empty RefPtr on error.
    */
diff --git a/gio/src/gio_docs_override.xml b/gio/src/gio_docs_override.xml
index d06bd060..1a3a3886 100644
--- a/gio/src/gio_docs_override.xml
+++ b/gio/src/gio_docs_override.xml
@@ -1765,7 +1765,7 @@ Activation roots are typically used in #GVolumeMonitor
 implementations to find the underlying mount to shadow, see
 g_mount_is_shadowed() for more details.
 
-
+Since: 2.18
 </description>
 <parameters>
 <parameter name="volume">
@@ -1775,8 +1775,6 @@ g_mount_is_shadowed() for more details.
 </parameters>
 <return> the activation root of @volume or %NULL. Use
 g_object_unref() to free.
-
-Since: 2.18
 </return>
 </function>
 
diff --git a/gio/src/mount.hg b/gio/src/mount.hg
index d50a4f1e..bf2f83fd 100644
--- a/gio/src/mount.hg
+++ b/gio/src/mount.hg
@@ -118,6 +118,7 @@ public:
    *
    * @param operation A mount operation.
    * @param slot A callback which will be called when the operation is completed or canceled.
+   * @param flags Flags affecting the operation.
    */
   void remount(const Glib::RefPtr<MountOperation>& operation, const SlotAsyncReady& slot, MountMountFlags flags = MOUNT_MOUNT_NONE);
 
@@ -128,6 +129,7 @@ public:
    * actually be unmounted.
    *
    * @param operation A mount operation.
+   * @param flags Flags affecting the operation.
    */
   void remount(const Glib::RefPtr<MountOperation>& operation, MountMountFlags flags = MOUNT_MOUNT_NONE);
 
@@ -136,6 +138,8 @@ public:
    * Remounting is useful when some setting affecting the operation of the volume has been changed, as this may need a remount
    * to take affect. While this is semantically equivalent with unmounting and then remounting, not all backends might need to
    * actually be unmounted.
+   *
+   * @param flags Flags affecting the operation.
    */
   void remount(MountMountFlags flags = MOUNT_MOUNT_NONE);
   _IGNORE(g_mount_remount)
@@ -160,7 +164,7 @@ public:
   /** Tries to guess the type of content stored on the mount.
    * Returns one or more textual identifiers of well-known content types (typically
    * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
-   * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> specification for more on x-content types.
+   * memory cards. See the <a href="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</a> specification for more on x-content types.
    *
    * This is an asynchronous operation, and is finished by calling
    * guess_content_type_finish().
@@ -176,7 +180,7 @@ public:
   /** Tries to guess the type of content stored on the mount.
    * Returns one or more textual identifiers of well-known content types (typically
    * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
-   * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> specification for more on x-content types.
+   * memory cards. See the <a href="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</a> specification for more on x-content types.
    *
    * This is an asynchronous operation, and is finished by calling
    * guess_content_type_finish().
@@ -191,7 +195,7 @@ public:
   /** Tries to guess the type of content stored on the mount.
    * Returns one or more textual identifiers of well-known content types (typically
    * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
-   * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> specification for more on x-content types.
+   * memory cards. See the <a href="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</a> specification for more on x-content types.
    *
    * @param force_rescan Whether to force a rescan of the content. Otherwise a cached result will be used if available.
    *
diff --git a/gio/src/mountoperation.hg b/gio/src/mountoperation.hg
index 2b370eb8..450de593 100644
--- a/gio/src/mountoperation.hg
+++ b/gio/src/mountoperation.hg
@@ -71,7 +71,7 @@ public:
                g_mount_operation_set_domain)
   _WRAP_METHOD(PasswordSave get_password_save() const,
                g_mount_operation_get_password_save)
-  _WRAP_METHOD(void set_password_save(PasswordSave password_save),
+  _WRAP_METHOD(void set_password_save(PasswordSave save),
                g_mount_operation_set_password_save)
   _WRAP_METHOD(int get_choice() const, g_mount_operation_get_choice)
   _WRAP_METHOD(void set_choice(int choice), g_mount_operation_set_choice)
diff --git a/gio/src/outputstream.hg b/gio/src/outputstream.hg
index 3ba1aec2..39b27e47 100644
--- a/gio/src/outputstream.hg
+++ b/gio/src/outputstream.hg
@@ -313,6 +313,7 @@ public:
    * @param source An InputStream.
    * @param slot Callback slot to call when the request is satisfied.
    * @param cancellable Cancellable object.
+   * @param flags A set of OutputStreamSpliceFlags.
    * @param io_priority The io priority of the request.
    */
   void splice_async(const Glib::RefPtr<InputStream>& source, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, OutputStreamSpliceFlags flags = OUTPUT_STREAM_SPLICE_NONE, int io_priority = Glib::PRIORITY_DEFAULT);
@@ -327,6 +328,7 @@ public:
    *
    * @param source An InputStream.
    * @param slot Callback slot to call when the request is satisfied.
+   * @param flags A set of OutputStreamSpliceFlags.
    * @param io_priority The io priority of the request.
    */
   void splice_async(const Glib::RefPtr<InputStream>& source, const SlotAsyncReady& slot, OutputStreamSpliceFlags flags = OUTPUT_STREAM_SPLICE_NONE, int io_priority = Glib::PRIORITY_DEFAULT);
diff --git a/gio/src/proxy.hg b/gio/src/proxy.hg
index 7b0eb7bf..a7d58088 100644
--- a/gio/src/proxy.hg
+++ b/gio/src/proxy.hg
@@ -55,7 +55,7 @@ public:
   _WRAP_METHOD(static Glib::RefPtr<Proxy> get_default_for_protocol(const Glib::ustring& protocol), g_proxy_get_default_for_protocol)
 
   _WRAP_METHOD(Glib::RefPtr<IOStream> connect(const Glib::RefPtr<IOStream>& connection,
-    const Glib::RefPtr<const ProxyAddress>& proxy_adress, const Glib::RefPtr<Cancellable>& cancellable), g_proxy_connect, errthrow)
+    const Glib::RefPtr<const ProxyAddress>& proxy_address, const Glib::RefPtr<Cancellable>& cancellable), g_proxy_connect, errthrow)
 
   /** An Asynchronous version of connect().
    */
diff --git a/gio/src/proxyresolver.hg b/gio/src/proxyresolver.hg
index 61189afe..5b6d392e 100644
--- a/gio/src/proxyresolver.hg
+++ b/gio/src/proxyresolver.hg
@@ -58,7 +58,7 @@ public:
 						 const Glib::RefPtr<Cancellable>& cancellable), g_proxy_resolver_lookup, errthrow)
 
   /** Looks into the system proxy configuration to determine what proxy, if any, to use to connect to uri.
-   * The returned proxy URIs are of the form <protocol>://[user[:password]@]host:port or direct://, where <protocol> could be http, rtsp, socks or other proxying protocol.
+   * The returned proxy URIs are of the form \<protocol\>://[user[:password]\@]host:port or direct://, where \<protocol\> could be http, rtsp, socks or other proxying protocol.
    *
    * If you don't know what network protocol is being used on the socket, you should use none as the URI protocol.
    * In this case, the resolver might still return a generic proxy type (such as SOCKS), but would not return protocol-specific proxy types (such as http).
diff --git a/gio/src/resolver.hg b/gio/src/resolver.hg
index 72bc8a10..1acff313 100644
--- a/gio/src/resolver.hg
+++ b/gio/src/resolver.hg
@@ -75,7 +75,7 @@ public:
   /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call
    * lookup_by_name_finish() to get the result. See lookup_by_name() for more details.
    *
-   * @param hostname hostname The hostname to look up.
+   * @param hostname The hostname to look up.
    * @param slot A callback slot to call after the resolution completes.
    * @param cancellable A Cancellable object which can be used to cancel the operation.
    */
@@ -84,7 +84,7 @@ public:
   /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call
    * lookup_by_name_finish() to get the result. See lookup_by_name() for more details.
    *
-   * @param hostname hostname The hostname to look up.
+   * @param hostname The hostname to look up.
    * @param slot A callback slot to call after the resolution completes.
    */
   void lookup_by_name_async(const Glib::ustring& hostname, const SlotAsyncReady& slot);
@@ -98,7 +98,6 @@ public:
    * lookup_by_address_finish() to get the final result.
    *
    * @param address The address to reverse-resolve.
-   * @param hostname hostname The hostname to look up.
    * @param slot A callback slot to call after the resolution completes.
    * @param cancellable A Cancellable object which can be used to cancel the operation.
    */
@@ -108,7 +107,6 @@ public:
    * lookup_by_address_finish() to get the final result.
    *
    * @param address The address to reverse-resolve.
-   * @param hostname hostname The hostname to look up.
    * @param slot A callback slot to call after the resolution completes.
    */
   void lookup_by_address_async(const Glib::RefPtr<InetAddress>& address, const SlotAsyncReady& slot);
diff --git a/gio/src/settings.hg b/gio/src/settings.hg
index daf6af77..37e3ea24 100644
--- a/gio/src/settings.hg
+++ b/gio/src/settings.hg
@@ -52,13 +52,13 @@ public:
 
   _WRAP_METHOD(bool set_value(const Glib::ustring& key, const Glib::VariantBase& value),  g_settings_set_value)
 
-  /** Gets the value that is stored in the settings for a @key.
+  /** Gets the value that is stored in the settings for a @a key.
    *
    * It is a programmer error to give a @a key that isn't contained in the
    * schema for the settings.
    *
-   * @param  key The key to get the value for.
-   * @param A Variant of the expected type.
+   * @param key The key to get the value for.
+   * @param value A Variant of the expected type.
    *
    * @newin{2,28}
    */
diff --git a/gio/src/socket.hg b/gio/src/socket.hg
index 602d0452..7b5188dd 100644
--- a/gio/src/socket.hg
+++ b/gio/src/socket.hg
@@ -100,7 +100,8 @@ protected:
 
 public:
   _WRAP_METHOD_DOCS_ONLY(g_socket_new)
-  /** @throw Glib::Error
+  /** @param cancellable A Cancellable, or <tt>0</tt>.
+   * @throw Glib::Error
    */
   static Glib::RefPtr<Socket>
   create(SocketFamily family, SocketType type, SocketProtocol protocol,
@@ -112,7 +113,8 @@ public:
   _IGNORE(g_socket_connection_factory_create_connection)
 
   _WRAP_METHOD_DOCS_ONLY(g_socket_new_from_fd)
-  /** @throw Glib::Error
+  /** @param cancellable A Cancellable, or <tt>0</tt>.
+   * @throw Glib::Error
    */
   static Glib::RefPtr<Socket> create_from_fd(int fd, const Glib::RefPtr<Cancellable>&
                                              cancellable = Glib::RefPtr<Cancellable>());
@@ -203,7 +205,7 @@ public:
   _WRAP_METHOD(void set_multicast_ttl(guint ttl), g_socket_set_multicast_ttl)
 
   _WRAP_METHOD(bool join_multicast_group(const Glib::RefPtr<InetAddress>& group, bool source_specific, const std::string& iface{?}), g_socket_join_multicast_group, errthrow)
-  _WRAP_METHOD(bool leave_multicast_group(const Glib::RefPtr<InetAddress>& ggroup, bool source_specific, const std::string& iface{?}), g_socket_leave_multicast_group, errthrow)
+  _WRAP_METHOD(bool leave_multicast_group(const Glib::RefPtr<InetAddress>& group, bool source_specific, const std::string& iface{?}), g_socket_leave_multicast_group, errthrow)
 
 
   _WRAP_PROPERTY("blocking", bool)
diff --git a/gio/src/socketclient.hg b/gio/src/socketclient.hg
index b46121f8..5331a1ee 100644
--- a/gio/src/socketclient.hg
+++ b/gio/src/socketclient.hg
@@ -141,7 +141,7 @@ public:
   _WRAP_METHOD(void set_enable_proxy(bool enable), g_socket_client_set_enable_proxy)
 
   _WRAP_METHOD(guint get_timeout() const, g_socket_client_get_timeout)
-  _WRAP_METHOD(void set_timeout(guint enable), g_socket_client_set_timeout)
+  _WRAP_METHOD(void set_timeout(guint timeout), g_socket_client_set_timeout)
 
   _WRAP_METHOD(void add_application_proxy(const Glib::ustring& protocol), g_socket_client_add_application_proxy)
 
diff --git a/gio/src/themedicon.hg b/gio/src/themedicon.hg
index 8ecadf8e..44aa2cf2 100644
--- a/gio/src/themedicon.hg
+++ b/gio/src/themedicon.hg
@@ -50,7 +50,7 @@ protected:
   /** Creates a new themed icon for @ iconname, and optionally all the names that can be created by shortening @a iconname at '-' characters.
    *
    * @param iconname A string containing an icon name.
-   * use_default_callbacks Whether to use all the names that can be created by shortening @a iconname at '-' characters.
+   * @param use_default_callbacks Whether to use all the names that can be created by shortening @a iconname at '-' characters.
    */
   explicit ThemedIcon(const std::string& iconname, bool use_default_callbacks = false);
   _IGNORE(g_themed_icon_new, g_themed_icon_new_with_default_fallbacks)
@@ -59,7 +59,7 @@ public:
   /** Creates a new themed icon for @ iconname, and optionally all the names that can be created by shortening @a iconname at '-' characters.
    *
    * @param iconname A string containing an icon name.
-   * use_default_callbacks Whether to use all the names that can be created by shortening @a iconname at '-' characters.
+   * @param use_default_callbacks Whether to use all the names that can be created by shortening @a iconname at '-' characters.
    */
   _WRAP_CREATE(const std::string& iconname, bool use_default_callbacks = false)
 
diff --git a/gio/src/volume.hg b/gio/src/volume.hg
index 72329ef7..c69c3daa 100644
--- a/gio/src/volume.hg
+++ b/gio/src/volume.hg
@@ -95,27 +95,32 @@ public:
   /** Mounts a volume.
    * This is an asynchronous operation, and is finished by calling mount_finish() with the AsyncResult data returned in the callback slot.
    *
+   * @param mount_operation A mount operation.
    * @param slot A callback which will be called when the operation is completed or canceled.
    * @param cancellable A cancellable object which can be used to cancel the operation.
-   * @param mount_operation A mount operation.
+   * @param flags Flags affecting the operation.
    */
   void mount(const Glib::RefPtr<MountOperation>& mount_operation, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, MountMountFlags flags = MOUNT_MOUNT_NONE);
 
   /** Mounts a volume.
    * This is an asynchronous operation, and is finished by calling mount_finish() with the AsyncResult data returned in the callback slot.
    *
-   * @param slot A callback which will be called when the operation is completed or canceled.
    * @param mount_operation A mount operation.
+   * @param slot A callback which will be called when the operation is completed or canceled.
+   * @param flags Flags affecting the operation.
    */
   void mount(const Glib::RefPtr<MountOperation>& mount_operation, const SlotAsyncReady& slot, MountMountFlags flags = MOUNT_MOUNT_NONE);
 
   /** Mounts a volume.
    *
    * @param mount_operation A mount operation.
+   * @param flags Flags affecting the operation.
    */
   void mount(const Glib::RefPtr<MountOperation>& mount_operation, MountMountFlags flags = MOUNT_MOUNT_NONE);
 
   /** Mounts a volume.
+   *
+   * @param flags Flags affecting the operation.
    */
   void mount(MountMountFlags flags = MOUNT_MOUNT_NONE);