From 9e56d39bb477a64512c50b6c7beb1c94002e02cf Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:23:34 +0000 Subject: [PATCH 01/12] docs: Ignore some generated source files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit dep-list.c isn’t generated, but contains non-documentation gtk-doc-style comments which are probably better left in place, since the code is partially external to GLib. Signed-off-by: Philip Withnall --- docs/reference/gio/meson.build | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/reference/gio/meson.build b/docs/reference/gio/meson.build index b67915c95..930a3b75c 100644 --- a/docs/reference/gio/meson.build +++ b/docs/reference/gio/meson.build @@ -118,6 +118,13 @@ if get_option('gtk_doc') ] endif + ignore_sources = [ + 'kqueue', + 'tests', + 'gdbus-daemon-generated.c', + 'xdp-dbus.c', + ] + # FIXME: More win32 headers were added to fix building gio-scan # FIXME: ExampleAnimal docs aren't built @@ -141,6 +148,9 @@ if get_option('gtk_doc') '--rebuild-types', '--ignore-headers=' + ' '.join(ignore_headers), ], + mkdb_args : [ + '--ignore-files=' + ' '.join(ignore_sources), + ], content_files : [ 'overview.xml', 'migrating-posix.xml', From 80fcb1bc26edca17a996ee293153f8e07cfc9198 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:25:55 +0000 Subject: [PATCH 02/12] headers: Add various missing G_DISABLE_DEPRECATED guards MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As pointed out by gtk-doc, these are all symbols which have been marked as deprecated, but which aren’t protected by a deprecation guard. We can’t use G_DEPRECATED_IN_* for them, as they are all non-function symbols. Instead, wrap them in #ifndef G_DISABLE_DEPRECATED. In some cases, we also need to wrap one or two functions which use the deprecated types in G_DISABLE_DEPRECATED too. Signed-off-by: Philip Withnall --- gio/gdtlsconnection.h | 2 ++ gio/gioenums.h | 2 ++ gio/gsimpleasyncresult.h | 3 +++ gio/gtlsconnection.h | 2 ++ glib/deprecated/gthread-deprecated.c | 7 ++++++- glib/gmacros.h | 2 ++ glib/gmem.h | 3 +++ glib/gtestutils.h | 2 ++ glib/gtrashstack.h | 4 ++++ gobject/gparam.h | 4 +++- gobject/gparamspecs.h | 8 ++++++++ gobject/gtype.h | 9 ++++++++- gobject/gvaluearray.h | 3 +++ 13 files changed, 48 insertions(+), 3 deletions(-) diff --git a/gio/gdtlsconnection.h b/gio/gdtlsconnection.h index 364be935e..2438de79f 100644 --- a/gio/gdtlsconnection.h +++ b/gio/gdtlsconnection.h @@ -129,11 +129,13 @@ void g_dtls_connection_set_require_close_notify (GDtlsConnec GLIB_AVAILABLE_IN_2_48 gboolean g_dtls_connection_get_require_close_notify (GDtlsConnection *conn); +#ifndef G_DISABLE_DEPRECATED GLIB_DEPRECATED_IN_2_60 void g_dtls_connection_set_rehandshake_mode (GDtlsConnection *conn, GTlsRehandshakeMode mode); GLIB_DEPRECATED_IN_2_60 GTlsRehandshakeMode g_dtls_connection_get_rehandshake_mode (GDtlsConnection *conn); +#endif /* !G_DISABLE_DEPRECATED */ GLIB_AVAILABLE_IN_2_48 gboolean g_dtls_connection_handshake (GDtlsConnection *conn, diff --git a/gio/gioenums.h b/gio/gioenums.h index 2fc69b6be..c4f39146d 100644 --- a/gio/gioenums.h +++ b/gio/gioenums.h @@ -1603,6 +1603,7 @@ typedef enum { G_TLS_AUTHENTICATION_REQUIRED } GTlsAuthenticationMode; +#ifndef G_DISABLE_DEPRECATED /** * GTlsRehandshakeMode: * @G_TLS_REHANDSHAKE_NEVER: Never allow rehandshaking @@ -1623,6 +1624,7 @@ typedef enum { G_TLS_REHANDSHAKE_SAFELY, G_TLS_REHANDSHAKE_UNSAFELY } GTlsRehandshakeMode; +#endif /* !G_DISABLE_DEPRECATED */ /** * GTlsPasswordFlags: diff --git a/gio/gsimpleasyncresult.h b/gio/gsimpleasyncresult.h index 8daa91d40..25ab53943 100644 --- a/gio/gsimpleasyncresult.h +++ b/gio/gsimpleasyncresult.h @@ -92,9 +92,12 @@ gboolean g_simple_async_result_get_op_res_gboolean (GSimpleAsyncResul +#ifndef G_DISABLE_DEPRECATED GLIB_AVAILABLE_IN_2_32 /* Also deprecated, but can't mark something both AVAILABLE and DEPRECATED */ void g_simple_async_result_set_check_cancellable (GSimpleAsyncResult *simple, GCancellable *check_cancellable); +#endif /* !G_DISABLE_DEPRECATED */ + GLIB_DEPRECATED_IN_2_46 gpointer g_simple_async_result_get_source_tag (GSimpleAsyncResult *simple); GLIB_DEPRECATED_IN_2_46 diff --git a/gio/gtlsconnection.h b/gio/gtlsconnection.h index 39ec3fa02..c436254a6 100644 --- a/gio/gtlsconnection.h +++ b/gio/gtlsconnection.h @@ -109,11 +109,13 @@ void g_tls_connection_set_require_close_notify (GTlsConnecti GLIB_AVAILABLE_IN_ALL gboolean g_tls_connection_get_require_close_notify (GTlsConnection *conn); +#ifndef G_DISABLE_DEPRECATED GLIB_DEPRECATED_IN_2_60 void g_tls_connection_set_rehandshake_mode (GTlsConnection *conn, GTlsRehandshakeMode mode); GLIB_DEPRECATED_IN_2_60 GTlsRehandshakeMode g_tls_connection_get_rehandshake_mode (GTlsConnection *conn); +#endif /* !G_DISABLE_DEPRECATED */ GLIB_AVAILABLE_IN_2_60 void g_tls_connection_set_advertised_protocols (GTlsConnection *conn, diff --git a/glib/deprecated/gthread-deprecated.c b/glib/deprecated/gthread-deprecated.c index c0ef4deff..76544502c 100644 --- a/glib/deprecated/gthread-deprecated.c +++ b/glib/deprecated/gthread-deprecated.c @@ -97,6 +97,9 @@ * Deprecated:2.32:POSIX threads are in use on all non-Windows systems. * Use G_OS_WIN32 to detect Windows. */ +#ifdef G_DISABLE_DEPRECATED +#undef G_THREADS_IMPL_POSIX +#endif /** * G_THREADS_IMPL_WIN32: @@ -105,7 +108,9 @@ * * Deprecated:2.32:Use G_OS_WIN32 to detect Windows. */ - +#ifdef G_DISABLE_DEPRECATED +#undef G_THREADS_IMPL_WIN32 +#endif /* {{{1 Exported Variables */ diff --git a/glib/gmacros.h b/glib/gmacros.h index cb78bd20c..1654b5c7b 100644 --- a/glib/gmacros.h +++ b/glib/gmacros.h @@ -82,6 +82,7 @@ #undef G_INLINE_DEFINE_NEEDED +#ifndef G_DISABLE_DEPRECATED /* For historical reasons we need to continue to support those who * define G_IMPLEMENT_INLINES to mean "don't implement this here". */ @@ -91,6 +92,7 @@ #else # define G_INLINE_FUNC static inline #endif /* G_IMPLEMENT_INLINES */ +#endif /* !G_DISABLE_DEPRECATED */ /* Provide macros to feature the GCC function attribute. */ diff --git a/glib/gmem.h b/glib/gmem.h index 81f8cdde3..923fa86d4 100644 --- a/glib/gmem.h +++ b/glib/gmem.h @@ -381,7 +381,10 @@ GLIB_VAR gboolean g_mem_gc_friendly; /* Memory profiler and checker, has to be enabled via g_mem_set_vtable() */ +#ifndef G_DISABLE_DEPRECATED GLIB_VAR GMemVTable *glib_mem_profiler_table; +#endif + GLIB_DEPRECATED_IN_2_46 void g_mem_profile (void); diff --git a/glib/gtestutils.h b/glib/gtestutils.h index 69c6015c5..adee4794d 100644 --- a/glib/gtestutils.h +++ b/glib/gtestutils.h @@ -337,6 +337,7 @@ void g_test_queue_destroy (GDestroyNotify destroy_func, gpointer destroy_data); #define g_test_queue_unref(gobject) g_test_queue_destroy (g_object_unref, gobject) +#ifndef G_DISABLE_DEPRECATED typedef enum { G_TEST_TRAP_SILENCE_STDOUT = 1 << 7, G_TEST_TRAP_SILENCE_STDERR = 1 << 8, @@ -346,6 +347,7 @@ typedef enum { GLIB_DEPRECATED_IN_2_38_FOR (g_test_trap_subprocess) gboolean g_test_trap_fork (guint64 usec_timeout, GTestTrapFlags test_trap_flags); +#endif /* !G_DISABLE_DEPRECATED */ typedef enum { G_TEST_SUBPROCESS_INHERIT_STDIN = 1 << 0, diff --git a/glib/gtrashstack.h b/glib/gtrashstack.h index 44b3c6c10..9c1db5169 100644 --- a/glib/gtrashstack.h +++ b/glib/gtrashstack.h @@ -33,6 +33,8 @@ G_BEGIN_DECLS +#ifndef G_DISABLE_DEPRECATED + typedef struct _GTrashStack GTrashStack; struct _GTrashStack { @@ -49,6 +51,8 @@ gpointer g_trash_stack_peek (GTrashStack **stack_p); GLIB_DEPRECATED_IN_2_48 guint g_trash_stack_height (GTrashStack **stack_p); +#endif /* !G_DISABLE_DEPRECATED */ + G_END_DECLS #endif /* __G_TRASH_STACK_H_ */ diff --git a/gobject/gparam.h b/gobject/gparam.h index 535b98035..d644586db 100644 --- a/gobject/gparam.h +++ b/gobject/gparam.h @@ -260,6 +260,8 @@ struct _GParamSpecClass /*< private >*/ gpointer dummy[4]; }; + +#ifndef G_DISABLE_DEPRECATED /** * GParameter: * @name: the parameter name @@ -275,7 +277,7 @@ struct _GParameter /* auxiliary structure for _setv() variants */ const gchar *name; GValue value; }; - +#endif /* !G_DISABLE_DEPRECATED */ /* --- prototypes --- */ GLIB_AVAILABLE_IN_ALL diff --git a/gobject/gparamspecs.h b/gobject/gparamspecs.h index 26045a368..1556cd5c2 100644 --- a/gobject/gparamspecs.h +++ b/gobject/gparamspecs.h @@ -452,7 +452,10 @@ G_BEGIN_DECLS * * Deprecated: 2.32: Use #GArray instead of #GValueArray */ +#ifndef G_DISABLE_DEPRECATED #define G_TYPE_PARAM_VALUE_ARRAY (g_param_spec_types[18]) +#endif + /** * G_IS_PARAM_SPEC_VALUE_ARRAY: * @pspec: a valid #GParamSpec instance @@ -463,7 +466,10 @@ G_BEGIN_DECLS * * Deprecated: 2.32: Use #GArray instead of #GValueArray */ +#ifndef G_DISABLE_DEPRECATED #define G_IS_PARAM_SPEC_VALUE_ARRAY(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_VALUE_ARRAY)) +#endif + /** * G_PARAM_SPEC_VALUE_ARRAY: * @pspec: a valid #GParamSpec instance @@ -472,7 +478,9 @@ G_BEGIN_DECLS * * Deprecated: 2.32: Use #GArray instead of #GValueArray */ +#ifndef G_DISABLE_DEPRECATED #define G_PARAM_SPEC_VALUE_ARRAY(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_VALUE_ARRAY, GParamSpecValueArray)) +#endif /** * G_TYPE_PARAM_OBJECT: diff --git a/gobject/gtype.h b/gobject/gtype.h index a3a07c6a3..0c0b49a8f 100644 --- a/gobject/gtype.h +++ b/gobject/gtype.h @@ -621,6 +621,7 @@ struct _GTypeQuery */ #define G_TYPE_FROM_INTERFACE(g_iface) (((GTypeInterface*) (g_iface))->g_type) +#ifndef G_DISABLE_DEPRECATED /** * G_TYPE_INSTANCE_GET_PRIVATE: * @instance: the instance of a type deriving from @private_type @@ -639,6 +640,7 @@ struct _GTypeQuery * Returns: (not nullable): a pointer to the private data structure */ #define G_TYPE_INSTANCE_GET_PRIVATE(instance, g_type, c_type) ((c_type*) g_type_instance_get_private ((GTypeInstance*) (instance), (g_type))) +#endif /* !G_DISABLE_DEPRECATED */ /** * G_TYPE_CLASS_GET_PRIVATE: @@ -657,6 +659,7 @@ struct _GTypeQuery */ #define G_TYPE_CLASS_GET_PRIVATE(klass, g_type, c_type) ((c_type*) g_type_class_get_private ((GTypeClass*) (klass), (g_type))) +#ifndef G_DISABLE_DEPRECATED /** * GTypeDebugFlags: * @G_TYPE_DEBUG_NONE: Print no messages @@ -681,13 +684,17 @@ typedef enum /*< skip >*/ G_TYPE_DEBUG_INSTANCE_COUNT = 1 << 2, G_TYPE_DEBUG_MASK = 0x07 } GTypeDebugFlags; - +#endif /* !G_DISABLE_DEPRECATED */ /* --- prototypes --- */ GLIB_DEPRECATED_IN_2_36 void g_type_init (void); + +#ifndef G_DISABLE_DEPRECATED GLIB_DEPRECATED_IN_2_36 void g_type_init_with_debug_flags (GTypeDebugFlags debug_flags); +#endif + GLIB_AVAILABLE_IN_ALL const gchar * g_type_name (GType type); GLIB_AVAILABLE_IN_ALL diff --git a/gobject/gvaluearray.h b/gobject/gvaluearray.h index d8b6bb55c..fde42144b 100644 --- a/gobject/gvaluearray.h +++ b/gobject/gvaluearray.h @@ -27,6 +27,8 @@ G_BEGIN_DECLS +#ifndef G_DISABLE_DEPRECATED + /** * G_TYPE_VALUE_ARRAY: * @@ -98,6 +100,7 @@ GValueArray* g_value_array_sort_with_data (GValueArray *value_array, GCompareDataFunc compare_func, gpointer user_data); +#endif /* !G_DISABLE_DEPRECATED */ G_END_DECLS From d55ed6755e4740303b1030331552534796505566 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:27:35 +0000 Subject: [PATCH 03/12] =?UTF-8?q?gdesktopappinfo:=20Fix=20an=20overly-spec?= =?UTF-8?q?ific=20=E2=80=98Since=E2=80=99=20documentation=20line?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This was causing gtk-doc to try and link to an API deprecation index which doesn’t exist. Signed-off-by: Philip Withnall --- gio/gdesktopappinfo.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c index 7d7425ea9..238141158 100644 --- a/gio/gdesktopappinfo.c +++ b/gio/gdesktopappinfo.c @@ -4710,7 +4710,7 @@ g_desktop_app_info_get_boolean (GDesktopAppInfo *info, * a %NULL-terminated string array or %NULL if the specified * key cannot be found. The array should be freed with g_strfreev(). * - * Since: 2.60.0 + * Since: 2.60 */ gchar ** g_desktop_app_info_get_string_list (GDesktopAppInfo *info, From a385135d8b4f2489b07230e987b2179d374c5d6b Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:28:05 +0000 Subject: [PATCH 04/12] gfile: Add some missing parameter documentation Signed-off-by: Philip Withnall --- gio/gfile.c | 1 + 1 file changed, 1 insertion(+) diff --git a/gio/gfile.c b/gio/gfile.c index 1cc69166a..f2ef3e86d 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -6934,6 +6934,7 @@ query_default_handler_query_info_cb (GObject *object, /** * g_file_query_default_handler_async: * @file: a #GFile to open + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: optional #GCancellable object, %NULL to ignore * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done * @user_data: (nullable): data to pass to @callback From 1a8f8be6d0641dd99299db168869ff8e1633ba89 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:28:32 +0000 Subject: [PATCH 05/12] gfile: Fix documentation links to non-existent symbols I presume this documentation was written before those APIs were renamed during code review. Signed-off-by: Philip Withnall --- gio/gfile.c | 2 +- gio/gfile.h | 12 ++++++------ gio/giotypes.h | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/gio/gfile.c b/gio/gfile.c index f2ef3e86d..24b136d80 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -7964,7 +7964,7 @@ g_file_real_measure_disk_usage_finish (GFile *file, * * By default, errors are only reported against the toplevel file * itself. Errors found while recursing are silently ignored, unless - * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags. + * %G_FILE_MEASURE_REPORT_ANY_ERROR is given in @flags. * * The returned size, @disk_usage, is in bytes and should be formatted * with g_format_size() in order to get something reasonable for showing diff --git a/gio/gfile.h b/gio/gfile.h index 6e25b0de0..9c9ea9572 100644 --- a/gio/gfile.h +++ b/gio/gfile.h @@ -80,14 +80,14 @@ typedef struct _GFileIface GFileIface; * @set_display_name: Sets the display name for a #GFile. * @set_display_name_async: Asynchronously sets a #GFile's display name. * @set_display_name_finish: Finishes asynchronously setting a #GFile's display name. - * @query_settable_attributes: Returns a list of #GFileAttributes that can be set. - * @_query_settable_attributes_async: Asynchronously gets a list of #GFileAttributes that can be set. + * @query_settable_attributes: Returns a list of #GFileAttributeInfos that can be set. + * @_query_settable_attributes_async: Asynchronously gets a list of #GFileAttributeInfos that can be set. * @_query_settable_attributes_finish: Finishes asynchronously querying settable attributes. - * @query_writable_namespaces: Returns a list of #GFileAttribute namespaces that are writable. - * @_query_writable_namespaces_async: Asynchronously gets a list of #GFileAttribute namespaces that are writable. + * @query_writable_namespaces: Returns a list of #GFileAttributeInfo namespaces that are writable. + * @_query_writable_namespaces_async: Asynchronously gets a list of #GFileAttributeInfo namespaces that are writable. * @_query_writable_namespaces_finish: Finishes asynchronously querying the writable namespaces. - * @set_attribute: Sets a #GFileAttribute. - * @set_attributes_from_info: Sets a #GFileAttribute with information from a #GFileInfo. + * @set_attribute: Sets a #GFileAttributeInfo. + * @set_attributes_from_info: Sets a #GFileAttributeInfo with information from a #GFileInfo. * @set_attributes_async: Asynchronously sets a file's attributes. * @set_attributes_finish: Finishes setting a file's attributes asynchronously. * @read_fn: Reads a file asynchronously. diff --git a/gio/giotypes.h b/gio/giotypes.h index 738e517bb..c9ad8dd90 100644 --- a/gio/giotypes.h +++ b/gio/giotypes.h @@ -335,7 +335,7 @@ typedef gboolean (* GFileReadMoreCallback) (const char *file_contents, * final async result would be reported). * * @current_size is in the same units as requested by the operation (see - * %G_FILE_DISK_USAGE_APPARENT_SIZE). + * %G_FILE_MEASURE_APPARENT_SIZE). * * The frequency of the updates is implementation defined, but is * ideally about once every 200ms. From 1f3375235bf3e82bff737731f01b425777e7bc46 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:29:44 +0000 Subject: [PATCH 06/12] =?UTF-8?q?docs:=20Stop=20formatting=20integer=20lit?= =?UTF-8?q?erals=20using=20=E2=80=98%=E2=80=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It makes gtk-doc try to link them. Signed-off-by: Philip Withnall --- gio/ginputstream.c | 2 +- gio/gmountoperation.c | 2 +- gio/gsocketclient.c | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/gio/ginputstream.c b/gio/ginputstream.c index e0b34eddc..9f67977b2 100644 --- a/gio/ginputstream.c +++ b/gio/ginputstream.c @@ -1045,7 +1045,7 @@ g_input_stream_skip_async (GInputStream *stream, * * Finishes a stream skip operation. * - * Returns: the size of the bytes skipped, or %-1 on error. + * Returns: the size of the bytes skipped, or `-1` on error. **/ gssize g_input_stream_skip_finish (GInputStream *stream, diff --git a/gio/gmountoperation.c b/gio/gmountoperation.c index c3f5d25d8..76a5024ff 100644 --- a/gio/gmountoperation.c +++ b/gio/gmountoperation.c @@ -799,7 +799,7 @@ g_mount_operation_set_password_save (GMountOperation *op, * Gets a choice from the mount operation. * * Returns: an integer containing an index of the user's choice from - * the choice's list, or %0. + * the choice's list, or `0`. **/ int g_mount_operation_get_choice (GMountOperation *op) diff --git a/gio/gsocketclient.c b/gio/gsocketclient.c index 9db7ca0be..d3711617f 100644 --- a/gio/gsocketclient.c +++ b/gio/gsocketclient.c @@ -457,7 +457,7 @@ g_socket_client_get_protocol (GSocketClient *client) * The sockets created by this object will use of the specified * protocol. * - * If @protocol is %0 that means to use the default + * If @protocol is %G_SOCKET_PROTOCOL_DEFAULT that means to use the default * protocol for the socket family and type. * * Since: 2.22 From 6837c34c84697df50d8300fdf7f32739361f4e7a Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:30:31 +0000 Subject: [PATCH 07/12] docs: Fix pluralised links to symbols MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While gtk-doc can currently detect a link to a symbol which has been pluralised by adding ‘s’, it can’t detect when ‘es’ is added. While that’s being fixed, reword the documentation so the links are generated correctly anyway. gtk-doc fix here: https://gitlab.gnome.org/GNOME/gtk-doc/merge_requests/22 Signed-off-by: Philip Withnall --- gio/gnetworkaddress.c | 2 +- gio/gproxyaddressenumerator.h | 2 +- gio/gsocketaddressenumerator.c | 2 +- gio/gsocketconnectable.c | 2 +- gio/gsocketconnectable.h | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/gio/gnetworkaddress.c b/gio/gnetworkaddress.c index 24af25c2c..df1bc3158 100644 --- a/gio/gnetworkaddress.c +++ b/gio/gnetworkaddress.c @@ -306,7 +306,7 @@ g_network_address_new (const gchar *hostname, * resolving `localhost`, and an IPv6 address for `localhost6`. * * g_network_address_get_hostname() will always return `localhost` for - * #GNetworkAddresses created with this constructor. + * a #GNetworkAddress created with this constructor. * * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress * diff --git a/gio/gproxyaddressenumerator.h b/gio/gproxyaddressenumerator.h index de9fa833e..470f1dc66 100644 --- a/gio/gproxyaddressenumerator.h +++ b/gio/gproxyaddressenumerator.h @@ -40,7 +40,7 @@ G_BEGIN_DECLS * GProxyAddressEnumerator: * * A subclass of #GSocketAddressEnumerator that takes another address - * enumerator and wraps its results in #GProxyAddresses as + * enumerator and wraps each of its results in a #GProxyAddress as * directed by the default #GProxyResolver. */ diff --git a/gio/gsocketaddressenumerator.c b/gio/gsocketaddressenumerator.c index 3defc7f89..ebbb5decf 100644 --- a/gio/gsocketaddressenumerator.c +++ b/gio/gsocketaddressenumerator.c @@ -30,7 +30,7 @@ * #GSocketAddressEnumerator is an enumerator type for #GSocketAddress * instances. It is returned by enumeration functions such as * g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator - * to list all the #GSocketAddresses which could be used to connect to that + * to list each #GSocketAddress which could be used to connect to that * #GSocketConnectable. * * Enumeration is typically a blocking operation, so the asynchronous methods diff --git a/gio/gsocketconnectable.c b/gio/gsocketconnectable.c index 76f349faf..e999e659c 100644 --- a/gio/gsocketconnectable.c +++ b/gio/gsocketconnectable.c @@ -121,7 +121,7 @@ g_socket_connectable_enumerate (GSocketConnectable *connectable) * @connectable: a #GSocketConnectable * * Creates a #GSocketAddressEnumerator for @connectable that will - * return #GProxyAddresses for addresses that you must connect + * return a #GProxyAddress for each of its addresses that you must connect * to via a proxy. * * If @connectable does not implement diff --git a/gio/gsocketconnectable.h b/gio/gsocketconnectable.h index 6528d4936..da882143a 100644 --- a/gio/gsocketconnectable.h +++ b/gio/gsocketconnectable.h @@ -35,7 +35,7 @@ G_BEGIN_DECLS /** * GSocketConnectable: * - * Interface for objects that contain or generate #GSocketAddresses. + * Interface for objects that contain or generate a #GSocketAddress. */ typedef struct _GSocketConnectableIface GSocketConnectableIface; From d6aa393578667575a2c31863e94023779d6794fc Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:36:06 +0000 Subject: [PATCH 08/12] gpollableoutputstream: Add vfunc documentation for writev_nonblocking This was missing from the original merge request. Signed-off-by: Philip Withnall --- gio/gpollableoutputstream.h | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/gio/gpollableoutputstream.h b/gio/gpollableoutputstream.h index c1e7ad889..c282afdec 100644 --- a/gio/gpollableoutputstream.h +++ b/gio/gpollableoutputstream.h @@ -49,6 +49,8 @@ typedef struct _GPollableOutputStreamInterface GPollableOutputStreamInterface; * @create_source: Creates a #GSource to poll the stream * @write_nonblocking: Does a non-blocking write or returns * %G_IO_ERROR_WOULD_BLOCK + * @writev_nonblocking: Does a vectored non-blocking write, or returns + * %G_POLLABLE_RETURN_WOULD_BLOCK * * The interface for pollable output streams. * @@ -61,6 +63,12 @@ typedef struct _GPollableOutputStreamInterface GPollableOutputStreamInterface; * implementation may return %TRUE when the stream is not actually * writable. * + * The default implementation of @writev_nonblocking calls + * g_pollable_output_stream_write_nonblocking() for each vector, and converts + * its return value and error (if set) to a #GPollableReturn. You should + * override this where possible to avoid having to allocate a #GError to return + * %G_IO_ERROR_WOULD_BLOCK. + * * Since: 2.28 */ struct _GPollableOutputStreamInterface From dd77a87cf80de4bb3036bedc0cd19980fba0db6c Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:36:49 +0000 Subject: [PATCH 09/12] docs: Fix various typos in linked symbol names Signed-off-by: Philip Withnall --- gio/gtlsdatabase.c | 2 +- gio/gunixfdlist.c | 2 +- gio/gunixfdmessage.c | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c index 821af97e0..58da11df3 100644 --- a/gio/gtlsdatabase.c +++ b/gio/gtlsdatabase.c @@ -744,7 +744,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_by_handle() for more information. + * g_tls_database_lookup_certificate_for_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/gunixfdlist.c b/gio/gunixfdlist.c index 6cb7df684..e8c4ac55e 100644 --- a/gio/gunixfdlist.c +++ b/gio/gunixfdlist.c @@ -23,7 +23,7 @@ * descriptors that it contains, closing them when finalized. * * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in - * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message() + * the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message() * and received using g_socket_receive_message(). * * Note that `` belongs to the UNIX-specific GIO diff --git a/gio/gunixfdmessage.c b/gio/gunixfdmessage.c index b80283b0b..3324651f7 100644 --- a/gio/gunixfdmessage.c +++ b/gio/gunixfdmessage.c @@ -22,7 +22,7 @@ * This #GSocketControlMessage contains a #GUnixFDList. * It may be sent using g_socket_send_message() and received using * g_socket_receive_message() over UNIX sockets (ie: sockets in the - * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied + * %G_SOCKET_FAMILY_UNIX family). The file descriptors are copied * between processes by the kernel. * * For an easier way to send and receive file descriptors over From e440249bd3c94ec9553c5617b152abf0bb575767 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:37:35 +0000 Subject: [PATCH 10/12] docs: Move some documentation comments from docs.c to their symbols MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It would be nice if docs.c eventually went away — it’s more maintainable for documentation comments to be next to the definition of the symbols they document. Move a few from docs.c, based on what I’ve been modifying recently. The documentation comments are unchanged apart from fixing an argument name for G_ALIGNOF. Signed-off-by: Philip Withnall --- glib/docs.c | 31 ------------------------------- glib/gmacros.h | 30 ++++++++++++++++++++++++++++++ glib/gtestutils.c | 22 ---------------------- glib/gtestutils.h | 21 +++++++++++++++++++++ 4 files changed, 51 insertions(+), 53 deletions(-) diff --git a/glib/docs.c b/glib/docs.c index cbe929a0a..729497afd 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -1845,23 +1845,6 @@ * arrays or arrays on the stack. */ -/** - * G_ALIGNOF - * @a: a type-name - * - * Return the minimal alignment required by the platform ABI for values of the given - * type. The address of a variable or struct member of the given type must always be - * a multiple of this alignment. For example, most platforms require int variables - * to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms. - * - * Note this is not necessarily the same as the value returned by GCC’s - * `__alignof__` operator, which returns the preferred alignment for a type. - * The preferred alignment may be a stricter alignment than the minimal - * alignment. - * - * Since: 2.60 - */ - /* Miscellaneous Macros {{{1 */ /** @@ -1873,20 +1856,6 @@ * needed so often by application programmers. */ -/** - * G_INLINE_FUNC: - * - * This macro used to be used to conditionally define inline functions - * in a compatible way before this feature was supported in all - * compilers. These days, GLib requires inlining support from the - * compiler, so your GLib-using programs can safely assume that the - * "inline" keywork works properly. - * - * Never use this macro anymore. Just say "static inline". - * - * Deprecated: 2.48: Use "static inline" instead - */ - /** * G_STMT_START: * diff --git a/glib/gmacros.h b/glib/gmacros.h index 1654b5c7b..08ddb51c9 100644 --- a/glib/gmacros.h +++ b/glib/gmacros.h @@ -82,6 +82,20 @@ #undef G_INLINE_DEFINE_NEEDED +/** + * G_INLINE_FUNC: + * + * This macro used to be used to conditionally define inline functions + * in a compatible way before this feature was supported in all + * compilers. These days, GLib requires inlining support from the + * compiler, so your GLib-using programs can safely assume that the + * "inline" keywork works properly. + * + * Never use this macro anymore. Just say "static inline". + * + * Deprecated: 2.48: Use "static inline" instead + */ + #ifndef G_DISABLE_DEPRECATED /* For historical reasons we need to continue to support those who * define G_IMPLEMENT_INLINES to mean "don't implement this here". @@ -831,6 +845,22 @@ * https://gitlab.gnome.org/GNOME/glib/merge_requests/538/diffs#note_390790. */ +/** + * G_ALIGNOF + * @type: a type-name + * + * Return the minimal alignment required by the platform ABI for values of the given + * type. The address of a variable or struct member of the given type must always be + * a multiple of this alignment. For example, most platforms require int variables + * to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms. + * + * Note this is not necessarily the same as the value returned by GCC’s + * `__alignof__` operator, which returns the preferred alignment for a type. + * The preferred alignment may be a stricter alignment than the minimal + * alignment. + * + * Since: 2.60 + */ #if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L && !defined(__cplusplus) #define G_ALIGNOF(type) _Alignof (type) #else diff --git a/glib/gtestutils.c b/glib/gtestutils.c index f5b75662c..a63d136a0 100644 --- a/glib/gtestutils.c +++ b/glib/gtestutils.c @@ -347,28 +347,6 @@ * Since: 2.16 */ -/** - * GTestTrapFlags: - * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to - * `/dev/null` so it cannot be observed on the console during test - * runs. The actual output is still captured though to allow later - * tests with g_test_trap_assert_stdout(). - * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to - * `/dev/null` so it cannot be observed on the console during test - * runs. The actual output is still captured though to allow later - * tests with g_test_trap_assert_stderr(). - * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the - * child process is shared with stdin of its parent process. - * It is redirected to `/dev/null` otherwise. - * - * Test traps are guards around forked tests. - * These flags determine what traps to set. - * - * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(), - * which is deprecated. g_test_trap_subprocess() uses - * #GTestSubprocessFlags. - */ - /** * GTestSubprocessFlags: * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child diff --git a/glib/gtestutils.h b/glib/gtestutils.h index adee4794d..5f8d06d15 100644 --- a/glib/gtestutils.h +++ b/glib/gtestutils.h @@ -338,6 +338,27 @@ void g_test_queue_destroy (GDestroyNotify destroy_func, #define g_test_queue_unref(gobject) g_test_queue_destroy (g_object_unref, gobject) #ifndef G_DISABLE_DEPRECATED +/** + * GTestTrapFlags: + * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to + * `/dev/null` so it cannot be observed on the console during test + * runs. The actual output is still captured though to allow later + * tests with g_test_trap_assert_stdout(). + * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to + * `/dev/null` so it cannot be observed on the console during test + * runs. The actual output is still captured though to allow later + * tests with g_test_trap_assert_stderr(). + * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the + * child process is shared with stdin of its parent process. + * It is redirected to `/dev/null` otherwise. + * + * Test traps are guards around forked tests. + * These flags determine what traps to set. + * + * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(), + * which is deprecated. g_test_trap_subprocess() uses + * #GTestSubprocessFlags. + */ typedef enum { G_TEST_TRAP_SILENCE_STDOUT = 1 << 7, G_TEST_TRAP_SILENCE_STDERR = 1 << 8, From 76b32508d2e11de90a28a863eb6bffc1401f2dd6 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:38:35 +0000 Subject: [PATCH 11/12] gdatetime: Unmark an unrelated comment as a documentation comment This was confusing gtk-doc. Signed-off-by: Philip Withnall --- glib/gdatetime.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/glib/gdatetime.c b/glib/gdatetime.c index d8309f857..c286954c4 100644 --- a/glib/gdatetime.c +++ b/glib/gdatetime.c @@ -2779,7 +2779,7 @@ format_z (GString *outstr, } #ifdef HAVE_LANGINFO_OUTDIGIT -/** Initializes the array with UTF-8 encoded alternate digits suitable for use +/* Initializes the array with UTF-8 encoded alternate digits suitable for use * in current locale. Returns NULL when current locale does not use alternate * digits or there was an error converting them to UTF-8. */ From ba09fa8500e998b700b874ed10468059c34b9916 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 7 Mar 2019 17:39:21 +0000 Subject: [PATCH 12/12] gvaluearray: Mark the whole of GValueArray as deprecated MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is not new; all of its methods have been deprecated for a long time. Make the deprecation more obvious, however, by marking the whole section as deprecated. Note that GArray can’t *quite* do everything that GValueArray could. See #1069 for work to fix this. This documentation block can be updated again once that’s fixed. Signed-off-by: Philip Withnall --- gobject/gvaluearray.c | 3 +++ 1 file changed, 3 insertions(+) diff --git a/gobject/gvaluearray.c b/gobject/gvaluearray.c index 553152d5a..83e03f7ec 100644 --- a/gobject/gvaluearray.c +++ b/gobject/gvaluearray.c @@ -55,6 +55,9 @@ * GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); * g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); * ]| + * + * Deprecated: 2.32: Use #GArray instead, if possible for the given use case, + * as described above. */ #define GROUP_N_VALUES (8) /* power of 2 !! */