[glib] docs: Fix various minor syntax errors in gtk-doc comments

From: Philip Withnall <pwithnall src gnome org>
To: commits-list gnome org
Cc:
Subject: [glib] docs: Fix various minor syntax errors in gtk-doc comments
Date: Tue, 7 Nov 2017 14:51:53 +0000 (UTC)
commit 8e8f4e6486c1578ae15d63835acd06f237324a6d
Author: Philip Withnall <withnall endlessm com>
Date:   Tue Nov 7 13:38:58 2017 +0000

    docs: Fix various minor syntax errors in gtk-doc comments
    
    This will fix a few broken links in the documentation, and shut up a
    load of gtk-doc warnings (but certainly not all of them).
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    https://bugzilla.gnome.org/show_bug.cgi?id=790015

 gio/gappinfo.c             |    2 +-
 gio/gbufferedinputstream.c |    2 +-
 gio/gcancellable.c         |    4 ++--
 gio/gdbusaddress.c         |    6 +++---
 gio/gdbusnamewatching.h    |    2 +-
 gio/gdtlsconnection.c      |    4 ++--
 gio/gioenums.h             |    2 +-
 gio/gmount.c               |    4 ++--
 gio/gsettingsbackend.c     |    4 ++--
 gio/gtask.c                |    2 +-
 gio/gtlsdatabase.c         |    4 ++--
 gio/gunixmounts.c          |    2 +-
 glib/docs.c                |    2 ++
 glib/glib-unix.c           |    2 +-
 glib/goption.c             |    4 ++--
 glib/gpoll.c               |    8 ++++----
 glib/gspawn.c              |    4 ++--
 glib/gtestutils.c          |    2 +-
 glib/gunicode.h            |    8 ++++----
 19 files changed, 35 insertions(+), 33 deletions(-)
---
diff --git a/gio/gappinfo.c b/gio/gappinfo.c
index 6e9f878..32e9b3f 100644
--- a/gio/gappinfo.c
+++ b/gio/gappinfo.c
@@ -768,7 +768,7 @@ g_app_info_launch_default_for_uri (const char         *uri,
  * g_app_info_launch_default_for_uri_async:
  * @uri: the uri to show
  * @context: (nullable): an optional #GAppLaunchContext
- * cancellable: (nullable): a #GCancellable
+ * @cancellable: (nullable): a #GCancellable
  * @callback: (nullable): a #GASyncReadyCallback to call when the request is done
  * @user_data: (nullable): data to pass to @callback
  *
diff --git a/gio/gbufferedinputstream.c b/gio/gbufferedinputstream.c
index f70ccb0..f5090d0 100644
--- a/gio/gbufferedinputstream.c
+++ b/gio/gbufferedinputstream.c
@@ -524,7 +524,7 @@ g_buffered_input_stream_fill_async (GBufferedInputStream *stream,
  *
  * Finishes an asynchronous read.
  *
- * Returns: a #gssize of the read stream, or %-1 on an error.
+ * Returns: a #gssize of the read stream, or `-1` on an error.
  */
 gssize
 g_buffered_input_stream_fill_finish (GBufferedInputStream  *stream,
diff --git a/gio/gcancellable.c b/gio/gcancellable.c
index b875ae7..d833bcf 100644
--- a/gio/gcancellable.c
+++ b/gio/gcancellable.c
@@ -594,7 +594,7 @@ g_cancellable_connect (GCancellable   *cancellable,
 /**
  * g_cancellable_disconnect:
  * @cancellable: (nullable): A #GCancellable or %NULL.
- * @handler_id: Handler id of the handler to be disconnected, or %0.
+ * @handler_id: Handler id of the handler to be disconnected, or `0`.
  *
  * Disconnects a handler from a cancellable instance similar to
  * g_signal_handler_disconnect().  Additionally, in the event that a
@@ -608,7 +608,7 @@ g_cancellable_connect (GCancellable   *cancellable,
  * signal handler is removed. See #GCancellable::cancelled for
  * details on how to use this.
  *
- * If @cancellable is %NULL or @handler_id is %0 this function does
+ * If @cancellable is %NULL or @handler_id is `0` this function does
  * nothing.
  *
  * Since: 2.22
diff --git a/gio/gdbusaddress.c b/gio/gdbusaddress.c
index 6fb3d2a..faee800 100644
--- a/gio/gdbusaddress.c
+++ b/gio/gdbusaddress.c
@@ -1702,10 +1702,10 @@ g_dbus_address_get_for_bus_sync (GBusType       bus_type,
  * Escape @string so it can appear in a D-Bus address as the value
  * part of a key-value pair.
  *
- * For instance, if @string is "/run/bus-for-:0",
- * this function would return "/run/bus-for-%3A0",
+ * For instance, if @string is `/run/bus-for-:0`,
+ * this function would return `/run/bus-for-%3A0`,
  * which could be used in a D-Bus address like
- * "unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0".
+ * `unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`.
  *
  * Returns: (transfer full): a copy of @string with all
  *     non-optionally-escaped bytes escaped
diff --git a/gio/gdbusnamewatching.h b/gio/gdbusnamewatching.h
index d803ecb..491e21e 100644
--- a/gio/gdbusnamewatching.h
+++ b/gio/gdbusnamewatching.h
@@ -54,7 +54,7 @@ typedef void (*GBusNameAppearedCallback) (GDBusConnection *connection,
  *
  * Invoked when the name being watched is known not to have to have a owner.
  *
- * This is also invoked when the #GDBusConection on which the watch was
+ * This is also invoked when the #GDBusConnection on which the watch was
  * established has been closed.  In that case, @connection will be
  * %NULL.
  *
diff --git a/gio/gdtlsconnection.c b/gio/gdtlsconnection.c
index 67a038d..cbcb720 100644
--- a/gio/gdtlsconnection.c
+++ b/gio/gdtlsconnection.c
@@ -112,7 +112,7 @@ g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
    *
    * The certificate database to use when verifying this TLS connection.
    * If no certificate database is set, then the default database will be
-   * used. See g_dtls_backend_get_default_database().
+   * used. See g_tls_backend_get_default_database().
    *
    * Since: 2.48
    */
@@ -294,7 +294,7 @@ g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
  *
  * Sets the certificate database that is used to verify peer certificates.
  * This is set to the default database by default. See
- * g_dtls_backend_get_default_database(). If set to %NULL, then
+ * g_tls_backend_get_default_database(). If set to %NULL, then
  * peer certificate validation will always set the
  * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
  * #GDtlsConnection::accept-certificate will always be emitted on
diff --git a/gio/gioenums.h b/gio/gioenums.h
index bedc81b..c6ee8c4 100644
--- a/gio/gioenums.h
+++ b/gio/gioenums.h
@@ -1690,7 +1690,7 @@ typedef enum /*< flags >*/ {
  * @G_TLS_DATABASE_LOOKUP_KEYPAIR: Restrict lookup to certificates that have
  *     a private key.
  *
- * Flags for g_tls_database_lookup_certificate_handle(),
+ * Flags for g_tls_database_lookup_certificate_for_handle(),
  * g_tls_database_lookup_certificate_issuer(),
  * and g_tls_database_lookup_certificates_issued_by().
  *
diff --git a/gio/gmount.c b/gio/gmount.c
index ff50a5c..0169ea5 100644
--- a/gio/gmount.c
+++ b/gio/gmount.c
@@ -54,9 +54,9 @@
  * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
  * #GAsyncReadyCallback.  The callback will be fired when the
  * operation has resolved (either with success or failure), and a
- * #GAsyncReady structure will be passed to the callback.  That
+ * #GAsyncResult structure will be passed to the callback.  That
  * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
- * and the #GAsyncReady data to see if the operation was completed
+ * and the #GAsyncResult data to see if the operation was completed
  * successfully.  If an @error is present when g_mount_unmount_with_operation_finish() 
  * is called, then it will be filled with any error information.
  **/
diff --git a/gio/gsettingsbackend.c b/gio/gsettingsbackend.c
index 0d5df0f..edc4ff4 100644
--- a/gio/gsettingsbackend.c
+++ b/gio/gsettingsbackend.c
@@ -70,12 +70,12 @@ static gboolean g_settings_has_backend;
  * implementations must carefully adhere to the expectations of
  * callers that are documented on each of the interface methods.
  *
- * Some of the GSettingsBackend functions accept or return a #GTree.
+ * Some of the #GSettingsBackend functions accept or return a #GTree.
  * These trees always have strings as keys and #GVariant as values.
  * g_settings_backend_create_tree() is a convenience function to create
  * suitable trees.
  *
- * The GSettingsBackend API is exported to allow third-party
+ * The #GSettingsBackend API is exported to allow third-party
  * implementations, but does not carry the same stability guarantees
  * as the public GIO API. For this reason, you have to define the
  * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
diff --git a/gio/gtask.c b/gio/gtask.c
index fd97f87..814ba94 100644
--- a/gio/gtask.c
+++ b/gio/gtask.c
@@ -507,7 +507,7 @@
  *   whether the task's callback can be invoked directly, or
  *   if it needs to be sent to another #GMainContext, or delayed
  *   until the next iteration of the current #GMainContext.)
- * - The "finish" functions for #GTask-based operations are generally
+ * - The "finish" functions for #GTask based operations are generally
  *   much simpler than #GSimpleAsyncResult ones, normally consisting
  *   of only a single call to g_task_propagate_pointer() or the like.
  *   Since g_task_propagate_pointer() "steals" the return value from
diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c
index 424d9c1..5a77b56 100644
--- a/gio/gtlsdatabase.c
+++ b/gio/gtlsdatabase.c
@@ -459,7 +459,7 @@ g_tls_database_class_init (GTlsDatabaseClass *klass)
  * adding any missing certificates to the chain.
  *
  * @chain is a chain of #GTlsCertificate objects each pointing to the next
- * certificate in the chain by its %issuer property. The chain may initially
+ * certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially
  * consist of one or more certificates. After the verification process is
  * complete, @chain may be modified by adding missing certificates, or removing
  * extra certificates. If a certificate anchor was found, then it is added to
@@ -741,7 +741,7 @@ g_tls_database_lookup_certificate_for_handle_async (GTlsDatabase            *sel
  * @error: a #GError pointer, or %NULL
  *
  * Finish an asynchronous lookup of a certificate by its handle. See
- * g_tls_database_lookup_certificate_handle() for more information.
+ * g_tls_database_lookup_certificate_by_handle() for more information.
  *
  * If the handle is no longer valid, or does not point to a certificate in
  * this database, then %NULL will be returned.
diff --git a/gio/gunixmounts.c b/gio/gunixmounts.c
index a3c40f5..fc37129 100644
--- a/gio/gunixmounts.c
+++ b/gio/gunixmounts.c
@@ -357,7 +357,7 @@ g_unix_is_system_fs_type (const char *fs_type)
 
 /**
  * g_unix_is_system_device_path:
- * @fs_type: a device path, e.g. `/dev/loop0` or `nfsd`
+ * @device_path: a device path, e.g. `/dev/loop0` or `nfsd`
  *
  * Determines if @device_path is considered a block device path which is only
  * used in implementation of the OS. This is primarily used for hiding
diff --git a/glib/docs.c b/glib/docs.c
index dff74f8..d6ac4b3 100644
--- a/glib/docs.c
+++ b/glib/docs.c
@@ -1999,6 +1999,8 @@
 
 /**
  * G_GNUC_CHECK_VERSION:
+ * @major: major version to check against
+ * @minor: minor version to check against
  *
  * Expands to a a check for a compiler with __GNUC__ defined and a version
  * greater than or equal to the major and minor numbers provided. For example,
diff --git a/glib/glib-unix.c b/glib/glib-unix.c
index a456357..6a5faf0 100644
--- a/glib/glib-unix.c
+++ b/glib/glib-unix.c
@@ -392,7 +392,7 @@ g_unix_fd_add_full (gint              priority,
  * g_unix_fd_add:
  * @fd: a file descriptor
  * @condition: IO conditions to watch for on @fd
- * @function: a #GPollFDFunc
+ * @function: a #GUnixFDSourceFunc
  * @user_data: data to pass to @function
  *
  * Sets a function to be called when the IO condition, as specified by
diff --git a/glib/goption.c b/glib/goption.c
index 78698cc..dc9ec3b 100644
--- a/glib/goption.c
+++ b/glib/goption.c
@@ -489,7 +489,7 @@ g_option_context_get_ignore_unknown_options (GOptionContext *context)
 
 /**
  * g_option_context_set_strict_posix:
- * @context: a #GoptionContext
+ * @context: a #GOptionContext
  * @strict_posix: the new value
  *
  * Sets strict POSIX mode.
@@ -530,7 +530,7 @@ g_option_context_set_strict_posix (GOptionContext *context,
 
 /**
  * g_option_context_get_strict_posix:
- * @context: a #GoptionContext
+ * @context: a #GOptionContext
  *
  * Returns whether strict POSIX code is enabled.
  *
diff --git a/glib/gpoll.c b/glib/gpoll.c
index 06ba705..849a04e 100644
--- a/glib/gpoll.c
+++ b/glib/gpoll.c
@@ -99,9 +99,9 @@ extern gboolean _g_main_poll_debug;
  * don't want to run the full main loop.
  *
  * Each element of @fds is a #GPollFD describing a single file
- * descriptor to poll. The %fd field indicates the file descriptor,
- * and the %events field indicates the events to poll for. On return,
- * the %revents fields will be filled with the events that actually
+ * descriptor to poll. The @fd field indicates the file descriptor,
+ * and the @events field indicates the events to poll for. On return,
+ * the @revents fields will be filled with the events that actually
  * occurred.
  *
  * On POSIX systems, the file descriptors in @fds can be any sort of
@@ -110,7 +110,7 @@ extern gboolean _g_main_poll_debug;
  * Windows, the easiest solution is to construct all of your
  * #GPollFDs with g_io_channel_win32_make_pollfd().
  *
- * Returns: the number of entries in @fds whose %revents fields
+ * Returns: the number of entries in @fds whose @revents fields
  * were filled in, or 0 if the operation timed out, or -1 on error or
  * if the call was interrupted.
  *
diff --git a/glib/gspawn.c b/glib/gspawn.c
index 93a287f..5122570 100644
--- a/glib/gspawn.c
+++ b/glib/gspawn.c
@@ -167,7 +167,7 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
  * If you are writing a GTK+ application, and the program you are spawning is a
  * graphical application too, then to ensure that the spawned program opens its
  * windows on the right screen, you may want to use #GdkAppLaunchContext,
- * #GAppLaunchcontext, or set the %DISPLAY environment variable.
+ * #GAppLaunchContext, or set the %DISPLAY environment variable.
  *
  * Note that the returned @child_pid on Windows is a handle to the child
  * process and not its identifier. Process handles and process identifiers
@@ -680,7 +680,7 @@ g_spawn_sync (const gchar          *working_directory,
  * If you are writing a GTK+ application, and the program you are spawning is a
  * graphical application too, then to ensure that the spawned program opens its
  * windows on the right screen, you may want to use #GdkAppLaunchContext,
- * #GAppLaunchcontext, or set the %DISPLAY environment variable.
+ * #GAppLaunchContext, or set the %DISPLAY environment variable.
  * 
  * Returns: %TRUE on success, %FALSE if an error was set
  */
diff --git a/glib/gtestutils.c b/glib/gtestutils.c
index 7b8b9f6..96b5343 100644
--- a/glib/gtestutils.c
+++ b/glib/gtestutils.c
@@ -336,7 +336,7 @@
  *
  * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(),
  * which is deprecated. g_test_trap_subprocess() uses
- * #GTestTrapSubprocessFlags.
+ * #GTestSubprocessFlags.
  */
 
 /**
diff --git a/glib/gunicode.h b/glib/gunicode.h
index e817677..e6934d2 100644
--- a/glib/gunicode.h
+++ b/glib/gunicode.h
@@ -411,10 +411,10 @@ typedef enum
  * @G_UNICODE_SCRIPT_NEWA:                 Newa. Since: 2.50
  * @G_UNICODE_SCRIPT_OSAGE:                Osage. Since: 2.50
  * @G_UNICODE_SCRIPT_TANGUT:               Tangut. Since: 2.50
- * @G_UNICODE_SCRIPT_MASARAM_GONDI,        Masaram Gondi. Since: 2.54
- * @G_UNICODE_SCRIPT_NUSHU,                Nushu. Since: 2.54
- * @G_UNICODE_SCRIPT_SOYOMBO,              Soyombo. Since: 2.54
- * @G_UNICODE_SCRIPT_ZANABAZAR_SQUARE      Zanabazar Square. Since: 2.54
+ * @G_UNICODE_SCRIPT_MASARAM_GONDI:        Masaram Gondi. Since: 2.54
+ * @G_UNICODE_SCRIPT_NUSHU:                Nushu. Since: 2.54
+ * @G_UNICODE_SCRIPT_SOYOMBO:              Soyombo. Since: 2.54
+ * @G_UNICODE_SCRIPT_ZANABAZAR_SQUARE:     Zanabazar Square. Since: 2.54
  *
  * The #GUnicodeScript enumeration identifies different writing
  * systems. The values correspond to the names as defined in the
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]