docs: fix up docs issues in gio/

gio/fen/fen-kernel.c

@@ -301,7 +301,6 @@ psource_new()
 
 /**
  * port_add:
- * @f:
  *
  * Unsafe, need lock fen_lock.
  * port_add will associate a GSource to @f->source

gio/gaction.c

@@ -62,6 +62,13 @@ G_DEFINE_INTERFACE (GAction, g_action, G_TYPE_OBJECT)
  * inside of a #GSimpleActionGroup.
  **/
 
+/**
+ * GAction:
+ *
+ * #GAction is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 /**
  * GActionInterface:
  * @get_name: the virtual function pointer for g_action_get_name()

gio/gactiongroup.c

@@ -76,6 +76,13 @@
  * calls to g_action_group_query_action().
  */
 
+/**
+ * GActionGroup:
+ *
+ * #GActionGroup is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 /**
  * GActionGroupInterface:
  * @has_action: the virtual function pointer for g_action_group_has_action()

gio/gactionmap.c

@@ -42,6 +42,13 @@
  * Since: 2.32
  **/
 
+/**
+ * GActionMap:
+ *
+ * #GActionMap is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 /**
  * GActionMapInterface:
  * @lookup_action: the virtual function pointer for g_action_map_lookup_action()

gio/gappinfo.c

@@ -825,7 +825,7 @@ g_app_launch_context_class_init (GAppLaunchContextClass *klass)
 
   object_class->finalize = g_app_launch_context_finalize;
 
-  /*
+  /**
    * GAppLaunchContext::launch-failed:
    * @context: the object emitting the signal
    * @startup_notify_id: the startup notification id for the failed launch
@@ -843,7 +843,7 @@ g_app_launch_context_class_init (GAppLaunchContextClass *klass)
                                          NULL, NULL, NULL,
                                          G_TYPE_NONE, 1, G_TYPE_STRING);
 
-  /*
+  /**
    * GAppLaunchContext::launched:
    * @context: the object emitting the signal
    * @info: the #GAppInfo that was just launched
@@ -1132,6 +1132,12 @@ g_app_info_monitor_class_init (GAppInfoMonitorClass *class)
 {
   GObjectClass *object_class = G_OBJECT_CLASS (class);
 
+  /**
+   * GAppInfoMonitor::changed:
+   *
+   * Signal emitted when the app info database for changes (ie: newly installed
+   * or removed applications).
+   **/
   g_app_info_monitor_changed_signal = g_signal_new ("changed", G_TYPE_APP_INFO_MONITOR, G_SIGNAL_RUN_FIRST,
                                                     0, NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
 

gio/gappinfo.h

@@ -78,6 +78,7 @@ typedef struct _GAppLaunchContextPrivate GAppLaunchContextPrivate;
  * @get_commandline: Gets the commandline for the #GAppInfo. Since 2.20
  * @get_display_name: Gets the display name for the #GAppInfo. Since 2.24
  * @set_as_last_used_for_type: Sets the application as the last used. See g_app_info_set_as_last_used_for_type().
+ * @get_supported_types: Retrieves the list of content types that @app_info claims to support.
  *
  * Application Information interface, for operating system portability.
  */

gio/gapplication.c

@@ -163,6 +163,14 @@
  * [gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c).
  */
 
+/**
+ * GApplication:
+ *
+ * #GApplication is an opaque data structure and can only be accessed
+ * using the following functions.
+ * Since: 2.28
+ */
+
 /**
  * GApplicationClass:
  * @startup: invoked on the primary instance immediately after registration
@@ -202,6 +210,8 @@
  * @dbus_unregister: invoked locally during unregistration, if the application
  *     is using its D-Bus backend. Use this to undo anything done by the
  *     @dbus_register vfunc. Since: 2.34
+ * @handle_local_options: invoked locally after the parsing of the commandline
+ *  options has occurred.
  *
  * Virtual function table for #GApplication.
  *

gio/gapplication.h

@@ -41,11 +41,6 @@ G_BEGIN_DECLS
 typedef struct _GApplicationPrivate                         GApplicationPrivate;
 typedef struct _GApplicationClass                           GApplicationClass;
 
-/**
- * GApplication:
- *
- * Since: 2.28
- */
 struct _GApplication
 {
   /*< private >*/

gio/gapplicationcommandline.c

@@ -200,6 +200,13 @@
  * [gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c)
  */
 
+/**
+ * GApplicationCommandLine:
+ *
+ * #GApplicationCommandLine is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
 /**
  * GApplicationCommandLineClass:
  *

gio/gdbusactiongroup.c

@@ -38,6 +38,13 @@
  * that is exported over D-Bus with g_dbus_connection_export_action_group().
  */
 
+/**
+ * GDBusActionGroup:
+ *
+ * #GDBusActionGroup is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
 struct _GDBusActionGroup
 {
   GObject parent_instance;

gio/gdbusmenumodel.c

@@ -37,6 +37,13 @@
  * g_dbus_connection_export_menu_model().
  */
 
+/**
+ * GDBusMenuModel:
+ *
+ * #GDBusMenuModel is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
 /*
  * There are 3 main (quasi-)classes involved here:
  *

gio/gdbusobject.c

@@ -37,6 +37,13 @@
  * interfaces.
  */
 
+/**
+ * GDBusObject:
+ *
+ * #GDBusObject is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
 typedef GDBusObjectIface GDBusObjectInterface;
 G_DEFINE_INTERFACE (GDBusObject, g_dbus_object, G_TYPE_OBJECT)
 

gio/gdbusobjectmanager.c

@@ -41,6 +41,13 @@
  * and #GDBusObjectManagerServer for the service-side implementation.
  */
 
+/**
+ * GDBusObjectManager:
+ *
+ * #GDBusObjectManager is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
 typedef GDBusObjectManagerIface GDBusObjectManagerInterface;
 G_DEFINE_INTERFACE (GDBusObjectManager, g_dbus_object_manager, G_TYPE_OBJECT)
 

gio/gdesktopappinfo.c

@@ -4308,6 +4308,13 @@ g_app_info_get_all (void)
 
 /* GDesktopAppInfoLookup interface {{{2 */
 
+/**
+ * GDesktopAppInfoLookup:
+ *
+ * #GDesktopAppInfoLookup is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 
 typedef GDesktopAppInfoLookupIface GDesktopAppInfoLookupInterface;

gio/gdesktopappinfo.h

@@ -116,7 +116,9 @@ gchar *                 g_desktop_app_info_get_action_name              (GDeskto
 #endif /* G_DISABLE_DEPRECATED */
 
 /**
- * GDesktopAppInfoLookup:
+ * GDesktopAppInfoLookupIface:
+ * @get_default_for_uri_scheme: Virtual method for
+ *  g_desktop_app_info_lookup_get_default_for_uri_scheme().
  *
  * Interface that is used by backends to associate default
  * handlers with URI schemes.

gio/gfile.h

@@ -150,6 +150,9 @@ typedef struct _GFileIface    		GFileIface;
  * @eject_mountable_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
  * @poll_mountable: Polls a mountable object for media changes. Since 2.22.
  * @poll_mountable_finish: Finishes an poll operation for media changes. Since 2.22.
+ * @measure_disk_usage: Recursively measures the disk usage of @file. Since 2.38
+ * @measure_disk_usage_async: Asynchronously recursively measures the disk usage of @file. Since 2.38
+ * @measure_disk_usage_finish: Finishes an asynchronous recursive measurement of the disk usage of @file. Since 2.38
  *
  * An interface for writing VFS file handles.
  **/

gio/gfiledescriptorbased.h

@@ -41,7 +41,9 @@ typedef struct _GFileDescriptorBasedIface   GFileDescriptorBasedIface;
 /**
  * GFileDescriptorBasedIface:
  * @g_iface: The parent interface.
+ * @get_fd: Gets the underlying file descriptor.
  *
+ * An interface for file descriptor based io objects.
  **/
 struct _GFileDescriptorBasedIface
 {

gio/gfileinfo.h

@@ -826,7 +826,7 @@ typedef struct _GFileInfoClass   GFileInfoClass;
  * was trashed. Corresponding #GFileAttributeType is
  * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
  *
- * Since: 2.24.
+ * Since: 2.24
  **/
 #define G_FILE_ATTRIBUTE_TRASH_ORIG_PATH "trash::orig-path"     /* byte string */
 
@@ -838,7 +838,7 @@ typedef struct _GFileInfoClass   GFileInfoClass;
  * was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss.
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
  *
- * Since: 2.24.
+ * Since: 2.24
  **/
 #define G_FILE_ATTRIBUTE_TRASH_DELETION_DATE "trash::deletion-date"  /* string */
 

gio/gicon.h

@@ -52,6 +52,7 @@ typedef struct _GIconIface GIconIface;
  * @from_tokens: Constructs a #GIcon from tokens. Set the #GError if
  * the tokens are malformed. Don't implement if the #GIcon can't be
  * serialized (Since 2.20).
+ * @serialize: Serializes a #GIcon into a #GVariant. Since: 2.38
  *
  * GIconIface is used to implement GIcon types for various
  * different systems. See #GThemedIcon and #GLoadableIcon for

gio/giomodule.c

@@ -224,12 +224,24 @@ static void      g_io_module_finalize      (GObject      *object);
 static gboolean  g_io_module_load_module   (GTypeModule  *gmodule);
 static void      g_io_module_unload_module (GTypeModule  *gmodule);
 
+/**
+ * GIOExtension:
+ *
+ * #GIOExtension is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
 struct _GIOExtension {
   char *name;
   GType type;
   gint priority;
 };
 
+/**
+ * GIOExtensionPoint:
+ *
+ * #GIOExtensionPoint is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
 struct _GIOExtensionPoint {
   GType required_type;
   char *name;

gio/gnetworkmonitor.c

@@ -48,6 +48,22 @@
  * Since: 2.32
  */
 
+/**
+ * GNetworkMonitorInterface:
+ * @g_iface: The parent interface.
+ * @network_changed: the virtual function pointer for the
+ *  GNetworkMonitor::network-changed signal.
+ * @can_reach: the virtual function pointer for g_network_monitor_can_reach()
+ * @can_reach_async: the virtual function pointer for
+ *  g_network_monitor_can_reach_async()
+ * @can_reach_finish: the virtual function pointer for
+ *  g_network_monitor_can_reach_finish()
+ *
+ * The virtual function table for #GNetworkMonitor.
+ *
+ * Since: 2.32
+ */
+
 G_DEFINE_INTERFACE_WITH_CODE (GNetworkMonitor, g_network_monitor, G_TYPE_OBJECT,
                               g_type_interface_add_prerequisite (g_define_type_id, G_TYPE_INITABLE);)
 

gio/gproxyaddress.c

@@ -43,6 +43,14 @@
  * Since: 2.26
  **/
 
+/**
+ * GProxyAddressClass:
+ *
+ * Class structure for #GProxyAddress.
+ *
+ * Since: 2.26
+ **/
+
 enum
 {
   PROP_0,

gio/gproxyresolver.c

@@ -41,6 +41,19 @@
  * the method g_socket_connectable_proxy_enumerate().
  */
 
+/**
+ * GProxyResolverInterface:
+ * @g_iface: The parent interface.
+ * @is_supported: the virtual function pointer for g_proxy_resolver_is_supported()
+ * @lookup: the virtual function pointer for g_proxy_resolver_lookup()
+ * @lookup_async: the virtual function pointer for
+ *  g_proxy_resolver_lookup_async()
+ * @lookup_finish: the virtual function pointer for
+ *  g_proxy_resolver_lookup_finish()
+ *
+ * The virtual function table for #GProxyResolver.
+ */
+
 G_DEFINE_INTERFACE (GProxyResolver, g_proxy_resolver, G_TYPE_OBJECT)
 
 static void

gio/gremoteactiongroup.c

@@ -55,6 +55,13 @@
  * Since: 2.32
  **/
 
+/**
+ * GRemoteActionGroup:
+ *
+ * #GRemoteActionGroup is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 /**
  * GRemoteActionGroupInterface:
  * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full()

gio/gresource.c

@@ -129,6 +129,13 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
  * Since: 2.32
  */
 
+/**
+ * GStaticResource:
+ *
+ * #GStaticResource is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 /**
  * g_resource_error_quark:
  *

gio/gsettings.c

@@ -230,6 +230,13 @@
  * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
  */
 
+/**
+ * GSettings:
+ *
+ * #GSettings is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 struct _GSettingsPrivate
 {
   /* where the signals go... */

gio/gsettingsbackend.h

@@ -59,6 +59,21 @@ G_BEGIN_DECLS
 typedef struct _GSettingsBackendPrivate                     GSettingsBackendPrivate;
 typedef struct _GSettingsBackendClass                       GSettingsBackendClass;
 
+/**
+ * GSettingsBackendClass:
+ * @read: virtual method to read a key's value
+ * @get_writable: virtual method to get if a key is writable
+ * @write: virtual method to change key's value
+ * @write_tree: virtual method to change a tree of keys
+ * @reset: virtual method to reset state
+ * @subscribe: virtual method to subscribe to key changes
+ * @unsubscribe: virtual method to unsubscribe to key changes
+ * @sync: virtual method to sync state
+ * @get_permission: virtual method to get permission of a key
+ * @read_user_value: virtual method to read user's key value
+ *
+ * Class structure for #GSettingsBackend.
+ */
 struct _GSettingsBackendClass
 {
   GObjectClass parent_class;

gio/gsettingsschema.c

@@ -128,6 +128,13 @@
  * Since: 2.32
  **/
 
+/**
+ * GSettingsSchemaKey:
+ *
+ * #GSettingsSchemaKey is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 /**
  * GSettingsSchema:
  *
@@ -836,13 +843,15 @@ ensure_schema_lists (void)
 /**
  * g_settings_list_schemas:
  *
+ * <!-- -->
+ *
  * Returns: (element-type utf8) (transfer none):  a list of #GSettings
  *   schemas that are available.  The list must not be modified or
  *   freed.
  *
  * Since: 2.26
  *
- * Deprecated:2.40: Use g_settings_schema_source_list_schemas() instead.
+ * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead.
  * If you used g_settings_list_schemas() to check for the presence of
  * a particular schema, use g_settings_schema_source_lookup() instead
  * of your whole loop.
@@ -858,13 +867,15 @@ g_settings_list_schemas (void)
 /**
  * g_settings_list_relocatable_schemas:
  *
+ * <!-- -->
+ *
  * Returns: (element-type utf8) (transfer none): a list of relocatable
  *   #GSettings schemas that are available.  The list must not be
  *   modified or freed.
  *
  * Since: 2.28
  *
- * Deprecated:2.40: Use g_settings_schema_source_list_schemas() instead
+ * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead
  **/
 const gchar * const *
 g_settings_list_relocatable_schemas (void)

gio/gsimpleaction.c

@@ -36,6 +36,14 @@
  *
  * See also #GtkAction.
  */
+
+/**
+ * GSimpleAction:
+ *
+ * #GSimpleAction is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 struct _GSimpleAction
 {
   GObject       parent_instance;

gio/gsocketcontrolmessage.h

@@ -54,6 +54,8 @@ typedef struct _GSocketControlMessageClass                  GSocketControlMessag
  * @get_type: gets the protocol specific type of the message.
  * @serialize: Writes out the message data.
  * @deserialize: Tries to deserialize a message.
+ *
+ * Class structure for #GSocketControlMessage.
  **/
 
 struct _GSocketControlMessageClass

gio/gsocketlistener.h

@@ -52,6 +52,8 @@ typedef struct _GSocketListenerClass                        GSocketListenerClass
 /**
  * GSocketListenerClass:
  * @changed: virtual method called when the set of socket listened to changes
+ *
+ * Class structure for #GSocketListener.
  **/
 struct _GSocketListenerClass
 {

gio/gsocketservice.h

@@ -49,6 +49,8 @@ typedef struct _GSocketServiceClass                         GSocketServiceClass;
 /**
  * GSocketServiceClass:
  * @incomming: signal emitted when new connections are accepted
+ *
+ * Class structure for #GSocketService.
  */
 struct _GSocketServiceClass
 {

gio/gtcpwrapperconnection.c

@@ -35,6 +35,13 @@
  * Since: 2.28
  */
 
+/**
+ * GTcpWrapperConnection:
+ *
+ * #GTcpWrapperConnection is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 #include "config.h"
 
 #include "gtcpwrapperconnection.h"

gio/gtlsbackend.c

@@ -60,6 +60,10 @@
  * @title: GTlsBackend
  * @short_description: TLS backend implementation
  * @include: gio/gio.h
+ *
+ * TLS (Transport Layer Security, aka SSL) backend
+ *
+ * Since: 2.28
  */
 
 /**

gio/gtlscertificate.c

@@ -524,7 +524,6 @@ g_tls_certificate_new_from_file (const gchar  *file,
 
 /**
  * g_tls_certificate_new_from_files:
-
  * @cert_file: file containing one or more PEM-encoded certificates to
  * import
  * @key_file: file containing a PEM-encoded private key to import

gio/gtlsclientconnection.h

@@ -34,6 +34,14 @@ G_BEGIN_DECLS
 
 typedef struct _GTlsClientConnectionInterface GTlsClientConnectionInterface;
 
+/**
+ * GTlsClientConnectionInterface:
+ * @g_iface: The parent interface.
+ *
+ * vtable for a #GTlsClientConnection implementation.
+ *
+ * Since: 2.26
+ */
 struct _GTlsClientConnectionInterface
 {
   GTypeInterface g_iface;

gio/gtlspassword.h

@@ -46,6 +46,15 @@ struct _GTlsPassword
   GTlsPasswordPrivate *priv;
 };
 
+/**
+ * GTlsPasswordClass:
+ * @get_value: virtual method for g_tls_password_get_value()
+ * @set_value: virtual method for g_tls_password_set_value()
+ * @get_default_warning: virtual method for g_tls_password_get_warning() if no
+ *  value has been set using g_tls_password_set_warning()
+ *
+ * Class structure for #GTlsPassword.
+ */
 struct _GTlsPasswordClass
 {
   GObjectClass parent_class;

gio/gtlsserverconnection.h

@@ -42,6 +42,14 @@ G_BEGIN_DECLS
  */
 typedef struct _GTlsServerConnectionInterface GTlsServerConnectionInterface;
 
+/**
+ * GTlsServerConnectionInterface:
+ * @g_iface: The parent interface.
+ *
+ * vtable for a #GTlsServerConnection implementation.
+ *
+ * Since: 2.26
+ */
 struct _GTlsServerConnectionInterface
 {
   GTypeInterface g_iface;

gio/gunixconnection.c

@@ -46,6 +46,13 @@
  * Since: 2.22
  */
 
+/**
+ * GUnixConnection:
+ *
+ * #GUnixConnection is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 G_DEFINE_TYPE_WITH_CODE (GUnixConnection, g_unix_connection,
 			 G_TYPE_SOCKET_CONNECTION,
   g_socket_connection_factory_register_type (g_define_type_id,

gio/gunixfdlist.c

@@ -31,6 +31,13 @@
  * file when using it.
  */
 
+/**
+ * GUnixFDList:
+ *
+ * #GUnixFDList is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 #include "config.h"
 
 #include <unistd.h>

gio/gunixfdmessage.c

@@ -34,6 +34,13 @@
  * file when using it.
  */
 
+/**
+ * GUnixFDMessage:
+ *
+ * #GUnixFDMessage is an opaque data structure and can only be accessed
+ * using the following functions.
+ **/
+
 #include "config.h"
 
 #include <unistd.h>

gio/gwin32mount.c

@@ -117,7 +117,7 @@ _win32_get_displayname (const char *drive)
   return name ? name : g_strdup (drive);
 }
 
-/**
+/*
  * _g_win32_mount_new:
  * @volume_monitor: a #GVolumeMonitor.
  * @path: a win32 path.

gio/kqueue/kqueue-exclusions.c

@@ -29,7 +29,7 @@
 static gboolean ke_debug_enabled = FALSE;
 #define KE_W if (ke_debug_enabled) g_warning
 
-/**
+/*
  * _ke_is_excluded:
  * @full_path - a path to file to check.
  *

gio/kqueue/kqueue-helper.c

@@ -428,7 +428,7 @@ process_kqueue_notifications (GIOChannel   *gioc,
 }
 
 
-/**
+/*
  * _kh_startup_impl:
  * @unused: unused
  *
@@ -479,7 +479,7 @@ _kh_startup_impl (gpointer unused)
 }
 
 
-/**
+/*
  * _kh_startup:
  * Kqueue backend initialization.
  *

gio/win32/gwinhttpfile.c

@@ -75,7 +75,7 @@ g_winhttp_file_init (GWinHttpFile *winhttp)
 {
 }
 
-/**
+/*
  * _g_winhttp_file_new:
  * @vfs: GWinHttpVfs to use
  * @uri: URI of the GWinHttpFile to create.

gio/win32/gwinhttpfileinputstream.c

@@ -92,7 +92,7 @@ g_winhttp_file_input_stream_init (GWinHttpFileInputStream *info)
 {
 }
 
-/**
+/*
  * g_winhttp_file_input_stream_new:
  * @file: the GWinHttpFile being read
  * @connection: handle to the HTTP connection, as from WinHttpConnect()

gio/win32/gwinhttpfileoutputstream.c

@@ -81,7 +81,7 @@ g_winhttp_file_output_stream_init (GWinHttpFileOutputStream *info)
 {
 }
 
-/**
+/*
  * g_winhttp_file_output_stream_new:
  * @file: the GWinHttpFile being read
  * @connection: handle to the HTTP connection, as from WinHttpConnect()