Various doc tweaks

21 files changed, 91 insertions, 67 deletions

diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index 4676bc02a..ce756433e 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -32,6 +32,10 @@
         <title>File System Monitoring</title>
         <xi:include href="xml/gfilemonitor.xml"/>
     </chapter>
+    <chapter id="utils">
+        <title>File-related Utilities</title>
+        <xi:include href="xml/gfilenamecompleter.xml"/>
+    </chapter>
     <chapter id="async">
         <title>Asynchronous I/O</title>
         <xi:include href="xml/gcancellable.xml"/>
@@ -161,10 +165,6 @@
       <xi:include href="xml/gdbusnamewatching.xml"/>
       <xi:include href="xml/gdbusproxy.xml"/>
     </chapter>
-    <chapter id="utils">
-        <title>Utilities</title>
-        <xi:include href="xml/gfilenamecompleter.xml"/>
-    </chapter>
     <chapter id="settings">
         <title>Settings</title>
         <xi:include href="xml/gsettings.xml"/>
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 3574e1ead..b49d501b7 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -3010,7 +3010,7 @@ GTlsCertificateFlags
 
 <SECTION>
 <FILE>gtlsbackend</FILE>
-<TITLE>GTlsBackend</FILE>
+<TITLE>GTlsBackend</TITLE>
 G_TLS_BACKEND_EXTENSION_POINT_NAME
 GTlsBackend
 GTlsBackendInterface
@@ -3033,7 +3033,6 @@ g_tls_backend_get_type
 <FILE>gtlscertificate</FILE>
 <TITLE>GTlsCertificate</TITLE>
 GTlsCertificate
-g_tls_certificate_new
 g_tls_certificate_new_from_pem
 g_tls_certificate_new_from_file
 g_tls_certificate_new_from_files
diff --git a/gio/gaction.c b/gio/gaction.c
index 1d1d16e34..6c2ee1db5 100644
--- a/gio/gaction.c
+++ b/gio/gaction.c
@@ -28,7 +28,7 @@ G_DEFINE_INTERFACE (GAction, g_action, G_TYPE_OBJECT)
 /**
  * SECTION:gaction
  * @title: GAction
- * @short_description: an action
+ * @short_description: An action
  *
  * #GAction represents a single named action.
  *
diff --git a/gio/gactiongroup.c b/gio/gactiongroup.c
index 5efb2096c..735f016be 100644
--- a/gio/gactiongroup.c
+++ b/gio/gactiongroup.c
@@ -28,7 +28,7 @@
 /**
  * SECTION:gactiongroup
  * @title: GActionGroup
- * @short_description: a group of actions
+ * @short_description: A group of actions
  *
  * #GActionGroup represents a group of actions.
  *
diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c
index 5931f57d7..c52398c3d 100644
--- a/gio/gapplicationcommandline.c
+++ b/gio/gapplicationcommandline.c
@@ -33,8 +33,7 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
 /**
  * SECTION:gapplicationcommandline
  * @title: GApplicationCommandLine
- * @short_description: A class representing a command-line invocation of
- *                     an application
+ * @short_description: A command-line invocation of an application
  * @see_also: #GApplication
  *
  * #GApplicationCommandLine represents a command-line invocation of
diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c
index ce3c8c9ac..a7648c984 100644
--- a/gio/gdesktopappinfo.c
+++ b/gio/gdesktopappinfo.c
@@ -48,6 +48,7 @@
 
 /**
  * SECTION:gdesktopappinfo
+ * @title: GDesktopAppInfo
  * @short_description: Application information from desktop files
  * @include: gio/gdesktopappinfo.h
  *
diff --git a/gio/gperiodic.c b/gio/gperiodic.c
index cf8482105..af7a2d583 100644
--- a/gio/gperiodic.c
+++ b/gio/gperiodic.c
@@ -34,7 +34,7 @@
  * of times per second and is capable of being put into synch with an
  * external time source.
  *
- * A number of #GPeriodicTickFunc<!-- -->s are registered with
+ * A number of #GPeriodicTickFuncs are registered with
  * g_periodic_add() and are called each time the clock "ticks".
  *
  * The tick functions can report "damage" (ie: updates that need to be
@@ -262,7 +262,7 @@ g_periodic_prepare (GSource *source,
     /* We need to run. */
     {
       gint64 remaining;
-     
+
       remaining = periodic->priv->last_run + 1000000 * (1 + periodic->priv->skip_frames) -
                   g_periodic_get_microticks (periodic);
 
@@ -354,8 +354,10 @@ g_periodic_dispatch (GSource     *source,
 }
 
 static void
-g_periodic_get_property (GObject *object, guint prop_id,
-                         GValue *value, GParamSpec *pspec)
+g_periodic_get_property (GObject    *object,
+                         guint       prop_id,
+                         GValue     *value,
+                         GParamSpec *pspec)
 {
   GPeriodic *periodic = G_PERIODIC (object);
 
@@ -379,8 +381,10 @@ g_periodic_get_property (GObject *object, guint prop_id,
 }
 
 static void
-g_periodic_set_property (GObject *object, guint prop_id,
-                         const GValue *value, GParamSpec *pspec)
+g_periodic_set_property (GObject      *object,
+                         guint         prop_id,
+                         const GValue *value,
+                         GParamSpec   *pspec)
 {
   GPeriodic *periodic = G_PERIODIC (object);
 
@@ -445,11 +449,25 @@ g_periodic_class_init (GPeriodicClass *class)
   object_class->set_property = g_periodic_set_property;
   object_class->finalize = g_periodic_finalize;
 
+  /**
+   * GPeriodic::tick
+   * @periodic: the #GPeriodic on which the signal was emitted
+   * @timestamp: the timestamp at the time of the tick
+   *
+   * The ::tick signal gets emitted whenever the clock "fires".
+   */
   g_periodic_tick = g_signal_new ("tick", G_TYPE_PERIODIC,
                                   G_SIGNAL_RUN_LAST,
                                   G_STRUCT_OFFSET(GPeriodicClass, tick),
                                   NULL, NULL, _gio_marshal_VOID__INT64,
                                   G_TYPE_NONE, 1, G_TYPE_INT64);
+
+  /**
+   * GPeriodic::repair:
+   * @periodic: the #GPeriodic on which the signal was emitted
+   *
+   * The ::repair signal gets emitted to start the "repair" phase.
+   */
   g_periodic_repair = g_signal_new ("repair", G_TYPE_PERIODIC,
                                     G_SIGNAL_RUN_LAST,
                                     G_STRUCT_OFFSET (GPeriodicClass, repair),
@@ -484,13 +502,14 @@ g_periodic_class_init (GPeriodicClass *class)
  * Temporarily blocks @periodic from running in order to bring it in
  * synch with an external time source.
  *
- * This function must be called from a handler of the "repair" signal.
+ * This function must be called from a handler of the #GPeriodic::repair
+ * signal.
  *
- * If this function is called, emission of the tick signal will be
- * suspended until g_periodic_unblock() is called an equal number of
- * times.  Once that happens, the "tick" signal will run immediately and
- * future "tick" signals will be emitted relative to the time at which
- * the last call to g_periodic_unblock() occured.
+ * If this function is called, emission of the #GPeriodic::tick signal
+ * will be suspended until g_periodic_unblock() is called an equal number
+ * of times. Once that happens, the ::tick signal will run immediately
+ * and future ::tick signals will be emitted relative to the time at
+ * which the last call to g_periodic_unblock() occured.
  *
  * Since: 2.28
  **/
@@ -510,9 +529,9 @@ g_periodic_block (GPeriodic *periodic)
  *
  * Reverses the effect of a previous call to g_periodic_block().
  *
- * If this call removes the last block, the tick signal is immediately
- * run.  The repair signal may also be run if the clock is marked as
- * damaged.
+ * If this call removes the last block, the ::tick signal is
+ * immediately run. The ::repair signal may also be run if the clock
+ * is marked as damaged.
  *
  * @unblock_time is the monotonic time, as per g_get_monotonic_time(),
  * at which the event causing the unblock occured.
@@ -545,20 +564,21 @@ g_periodic_unblock (GPeriodic       *periodic,
  * @user_data: data for @callback
  * @notify: for freeing @user_data when it is no longer needed
  *
- * Request periodic calls to @callback to start.  The periodicity of the
- * calls is determined by the 'hz' property.
+ * Request periodic calls to @callback to start. The periodicity of
+ * the calls is determined by the #GPeriodic:hz property.
  *
- * This function may not be called from a handler of the repair signal,
- * but it is perfectly reasonable to call it from a handler of the tick
- * signal.
+ * This function may not be called from a handler of the ::repair
+ * signal, but it is perfectly reasonable to call it from a handler
+ * of the ::tick signal.
  *
- * The callback may be cancelled later by using g_periodic_remove() on
- * the return value of this function.
+ * The callback may be cancelled later by using g_periodic_remove()
+ * on the return value of this function.
  *
  * Returns: a non-zero tag identifying this callback
  *
  * Since: 2.28
  **/
+
 /**
  * GPeriodicTickFunc:
  * @periodic: the #GPeriodic clock that is ticking
@@ -568,8 +588,8 @@ g_periodic_unblock (GPeriodic       *periodic,
  * The signature of the callback function that is called when the
  * #GPeriodic clock ticks.
  *
- * The @timestamp parameter is equal for all callbacks called during a
- * particular tick on a given clock.
+ * The @timestamp parameter is equal for all callbacks called during
+ * a particular tick on a given clock.
  *
  * Since: 2.28
  **/
@@ -605,9 +625,9 @@ g_periodic_add (GPeriodic         *periodic,
  *
  * @tag is the ID returned by that function.
  *
- * This function may not be called from a handler of the repair signal,
- * but it is perfectly reasonable to call it from a handler of the tick
- * signal.
+ * This function may not be called from a handler of the ::repair
+ * signal, but it is perfectly reasonable to call it from a handler
+ * of the ::tick signal.
  *
  * Since: 2.28
  **/
@@ -626,7 +646,7 @@ g_periodic_remove (GPeriodic *periodic,
 
       if (tick->id == tag)
         {
-          /* do this first incase the destroy notify re-enters */
+          /* do this first, in case the destroy notify re-enters */
           *iter = g_slist_remove (*iter, tick);
 
           if (tick->notify)
@@ -644,8 +664,8 @@ g_periodic_remove (GPeriodic *periodic,
  * g_periodic_damaged:
  * @periodic: a #GPeriodic clock
  *
- * Report damage and schedule the "repair" signal to be emitted during
- * the next repair phase.
+ * Report damage and schedule the ::repair signal to be emitted
+ * during the next repair phase.
  *
  * You may not call this function during the repair phase.
  *
@@ -666,7 +686,7 @@ g_periodic_damaged (GPeriodic *periodic)
  *
  * Gets the frequency of the clock.
  *
- * Returns: the frquency of the clock, in Hz
+ * Returns: the frequency of the clock, in Hz
  *
  * Since: 2.28
  **/
@@ -713,13 +733,14 @@ g_periodic_get_low_priority (GPeriodic *periodic)
 /**
  * g_periodic_new:
  * @hz: the frequency of the new clock in Hz (between 1 and 120)
- * @priority: the #GSource priority to run at
+ * @high_priority: the #GSource priority to run at
+ * @low_priority: ignore tasks below this priority
  *
  * Creates a new #GPeriodic clock.
  *
- * The created clock is attached to the thread-default main context in
- * effect at the time of the call to this function.  See
- * g_main_context_push_thread_default() for more information.
+ * The created clock is attached to the thread-default main context
+ * in effect at the time of the call to this function.
+ * See g_main_context_push_thread_default() for more information.
  *
  * Due to the fact that #GMainContext is only accurate to the nearest
  * millisecond, the frequency can not meaningfully get too close to
diff --git a/gio/gpermission.c b/gio/gpermission.c
index a6963505a..97a4fd949 100644
--- a/gio/gpermission.c
+++ b/gio/gpermission.c
@@ -28,7 +28,7 @@
 /**
  * SECTION:gpermission
  * @title: GPermission
- * @short_description: an object representing the permission to perform
+ * @short_description: An object representing the permission to perform
  *                     a certain action
  *
  * A #GPermission represents the status of the caller's permission to
diff --git a/gio/gpollableinputstream.c b/gio/gpollableinputstream.c
index 19946c666..d6937d835 100644
--- a/gio/gpollableinputstream.c
+++ b/gio/gpollableinputstream.c
@@ -35,8 +35,8 @@
  *
  * #GPollableInputStream is implemented by #GInputStream<!-- -->s that
  * can be polled for readiness to read. This can be used when
- * interfacing with a non-gio API that expects
- * unix-file-descriptor-style asynchronous I/O rather than gio-style.
+ * interfacing with a non-GIO API that expects
+ * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
  *
  * Since: 2.28
  */
@@ -125,9 +125,8 @@ g_pollable_input_stream_is_readable (GPollableInputStream *stream)
  *
  * As with g_pollable_input_stream_is_readable(), it is possible that
  * the stream may not actually be readable even after the source
- * triggers, so you should use
- * g_pollable_input_stream_read_nonblocking() rather than
- * g_input_stream_read() from the callback.
+ * triggers, so you should use g_pollable_input_stream_read_nonblocking()
+ * rather than g_input_stream_read() from the callback.
  *
  * Returns: a new #GSource
  *
diff --git a/gio/gpollableinputstream.h b/gio/gpollableinputstream.h
index 5def93ba8..3b57460fd 100644
--- a/gio/gpollableinputstream.h
+++ b/gio/gpollableinputstream.h
@@ -92,7 +92,7 @@ gssize   g_pollable_input_stream_read_nonblocking (GPollableInputStream  *stream
 						   GError               **error);
 
 /* Helper method for stream implementations */
-GSource *g_pollable_source_new                    (GObject               *stream);
+GSource *g_pollable_source_new                    (GObject               *pollable_stream);
 
 G_END_DECLS
 
diff --git a/gio/gpollableoutputstream.c b/gio/gpollableoutputstream.c
index cb9138aad..b4efb3fe3 100644
--- a/gio/gpollableoutputstream.c
+++ b/gio/gpollableoutputstream.c
@@ -36,8 +36,8 @@
  *
  * #GPollableOutputStream is implemented by #GOutputStream<!-- -->s that
  * can be polled for readiness to write. This can be used when
- * interfacing with a non-gio API that expects
- * unix-file-descriptor-style asynchronous I/O rather than gio-style.
+ * interfacing with a non-GIO API that expects
+ * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
  *
  * Since: 2.28
  */
@@ -126,9 +126,8 @@ g_pollable_output_stream_is_writable (GPollableOutputStream *stream)
  *
  * As with g_pollable_output_stream_is_writable(), it is possible that
  * the stream may not actually be writable even after the source
- * triggers, so you should use
- * g_pollable_output_stream_write_nonblocking() rather than
- * g_output_stream_write() from the callback.
+ * triggers, so you should use g_pollable_output_stream_write_nonblocking()
+ * rather than g_output_stream_write() from the callback.
  *
  * Returns: a new #GSource
  *
diff --git a/gio/gsettings.c b/gio/gsettings.c
index 724d67f6e..8c3bd72d2 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -42,7 +42,7 @@
 
 /**
  * SECTION:gsettings
- * @short_description: a high-level API for application settings
+ * @short_description: High-level API for application settings
  *
  * The #GSettings class provides a convenient API for storing and retrieving
  * application settings.
diff --git a/gio/gsettingsbackend.c b/gio/gsettingsbackend.c
index 475d05540..bd2fa2e82 100644
--- a/gio/gsettingsbackend.c
+++ b/gio/gsettingsbackend.c
@@ -49,7 +49,7 @@ struct _GSettingsBackendPrivate
 /**
  * SECTION:gsettingsbackend
  * @title: GSettingsBackend
- * @short_description: an interface for settings backend implementations
+ * @short_description: Interface for settings backend implementations
  * @include: gio/gsettingsbackend.h
  * @see_also: #GSettings, #GIOExtensionPoint
  *
diff --git a/gio/gsimpleaction.c b/gio/gsimpleaction.c
index e0eebaa2a..388ead3de 100644
--- a/gio/gsimpleaction.c
+++ b/gio/gsimpleaction.c
@@ -33,7 +33,7 @@ G_DEFINE_TYPE_WITH_CODE (GSimpleAction, g_simple_action, G_TYPE_OBJECT,
 /**
  * SECTION:gsimpleaction
  * @title: GSimpleAction
- * @short_description: a simple GSimpleAction
+ * @short_description: A simple GSimpleAction
  *
  * A #GSimpleAction is the obvious simple implementation of the #GSimpleAction
  * interface.  This is the easiest way to create an action for purposes of
diff --git a/gio/gsimpleactiongroup.c b/gio/gsimpleactiongroup.c
index 940a08142..ecc1dceae 100644
--- a/gio/gsimpleactiongroup.c
+++ b/gio/gsimpleactiongroup.c
@@ -25,7 +25,7 @@
 /**
  * SECTION:gsimpleactiongroup
  * @title: GSimpleActionGroup
- * @short_description: a simple GActionGroup implementation
+ * @short_description: A simple GActionGroup implementation
  *
  * #GSimpleActionGroup is a hash table filled with #GAction objects,
  * implementing the #GActionGroup interface.
diff --git a/gio/gsimplepermission.c b/gio/gsimplepermission.c
index 54cc00e21..c932c2ca3 100644
--- a/gio/gsimplepermission.c
+++ b/gio/gsimplepermission.c
@@ -28,7 +28,7 @@
 /**
  * SECTION:gsimplepermission
  * @title: GSimplePermission
- * @short_description: a GPermission that doesn't change value
+ * @short_description: A GPermission that doesn't change value
  *
  * #GSimplePermission is a trivial implementation of #GPermission that
  * represents a permission that is either always or never allowed.  The
diff --git a/gio/gtcpconnection.c b/gio/gtcpconnection.c
index 08364c180..f667862df 100644
--- a/gio/gtcpconnection.c
+++ b/gio/gtcpconnection.c
@@ -13,7 +13,7 @@
 /**
  * SECTION: gtcpconnection
  * @title: GTcpConnection
- * @short_description: a TCP GSocketConnection
+ * @short_description: A TCP GSocketConnection
  * @see_also: #GSocketConnection.
  *
  * This is the subclass of #GSocketConnection that is created
diff --git a/gio/gtcpwrapperconnection.c b/gio/gtcpwrapperconnection.c
index 47970ad97..7c2ff15ce 100644
--- a/gio/gtcpwrapperconnection.c
+++ b/gio/gtcpwrapperconnection.c
@@ -23,8 +23,7 @@
 /**
  * SECTION: gtcpwrapperconnection
  * @title: GTcpWrapperConnection
- * @short_description: a wrapper for non-#GSocketConnection-based
- *   #GIOStream<!-- -->s that are nonetheless based on a #GSocket
+ * @short_description: wrapper for non-GSocketConnection-based, GSocket-based GIOStreams
  * @see_also: #GSocketConnection.
  *
  * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
diff --git a/gio/gtlsbackend.c b/gio/gtlsbackend.c
index 6c93c48a7..64a979461 100644
--- a/gio/gtlsbackend.c
+++ b/gio/gtlsbackend.c
@@ -29,7 +29,7 @@
 /**
  * SECTION:gtls
  * @title: TLS Overview
- * @short_description: TLS (aka SSL) support for #GSocketConnection
+ * @short_description: TLS (aka SSL) support for GSocketConnection
  * @include: gio/gio.h
  *
  * #GTlsConnection and related classes provide TLS (Transport Layer
diff --git a/gio/gtlscertificate.c b/gio/gtlscertificate.c
index 876049cb9..be1f9af47 100644
--- a/gio/gtlscertificate.c
+++ b/gio/gtlscertificate.c
@@ -31,7 +31,7 @@
 /**
  * SECTION: gtlscertificate
  * @title: GTlsCertificate
- * @short_description: a TLS certificate
+ * @short_description: TLS certificate
  * @see_also: #GTlsConnection
  *
  * A certificate used for TLS authentication and encryption.
diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c
index e9e4250ed..e55f6f59c 100644
--- a/gio/gtlsconnection.c
+++ b/gio/gtlsconnection.c
@@ -666,6 +666,8 @@ g_tls_connection_certificate_accumulator (GSignalInvocationHint *ihint,
  * Used by #GTlsConnection implementations to emit the
  * #GTlsConnection::need-certificate signal.
  *
+ * Returns: a new #GTlsCertificate
+ *
  * Since: 2.28
  */
 GTlsCertificate *
@@ -681,10 +683,15 @@ g_tls_connection_emit_need_certificate (GTlsConnection *conn)
 /**
  * g_tls_connection_emit_accept_certificate:
  * @conn: a #GTlsConnection
+ * @peer_cert: the peer's #GTlsCertificate
+ * @errors: the problems with @peer_cert
  *
  * Used by #GTlsConnection implementations to emit the
  * #GTlsConnection::accept-certificate signal.
  *
+ * Return value: %TRUE if one of the signal handlers has returned
+ *     %TRUE to accept @peer_cert
+ *
  * Since: 2.28
  */
 gboolean