luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-26 07:26:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'gtkdoc-check-fix' into 'master'

Browse Source 
Various fixes to make gtkdoc-check pass on glib

See merge request GNOME/glib!978
This commit is contained in:
Philip Withnall 2020-01-31 13:23:42 +00:00
commit e855e30d6d
17 changed files with 278 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
.gitlab-ci.yml
View File

@ -10,13 +10,14 @@ cache:
- _ccache/
variables:
FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v6"
FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v7"
DEBIAN_IMAGE: "registry.gitlab.gnome.org/gnome/glib/debian-stable:v6"
ANDROID_IMAGE: "registry.gitlab.gnome.org/gnome/glib/android-ndk:v2"
MINGW_IMAGE: "registry.gitlab.gnome.org/gnome/glib/mingw:v2"
MESON_TEST_TIMEOUT_MULTIPLIER: 2
G_MESSAGES_DEBUG: all
MESON_COMMON_OPTIONS: "--buildtype debug --fatal-meson-warnings --wrap-mode=nodownload"
MESON_COMMON_OPTIONS_NO_WARNING: "--buildtype debug --wrap-mode=nodownload"
MESON_COMMON_OPTIONS: "${MESON_COMMON_OPTIONS_NO_WARNING} --fatal-meson-warnings"
.only-default:
only:
@ -44,7 +45,10 @@ fedora-x86_64:
variables:
CFLAGS: "-coverage -ftest-coverage -fprofile-arcs"
script:
- meson ${MESON_COMMON_OPTIONS}
# FIXME: Cannot use MESON_COMMON_OPTIONS here because meson warns about gtkdoc
# feature introduced in 0.52 but we only depends on 0.49. So we cannot build
# with --fatal-meson-warnings.
- meson ${MESON_COMMON_OPTIONS_NO_WARNING}
--werror
--default-library=both
--prefix=$HOME/glib-installed
@ -53,6 +57,7 @@ fedora-x86_64:
-Ddtrace=true
-Dfam=true
-Dinstalled_tests=true
-Dgtk_doc=true
_build
- ninja -C _build
- mkdir -p _coverage
@ -68,6 +73,15 @@ fedora-x86_64:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
- "_build/docs/reference/glib/glib-undeclared.txt"
- "_build/docs/reference/glib/glib-undocumented.txt"
- "_build/docs/reference/glib/glib-unused.txt"
- "_build/docs/reference/gobject/gobject-undeclared.txt"
- "_build/docs/reference/gobject/gobject-undocumented.txt"
- "_build/docs/reference/gobject/gobject-unused.txt"
- "_build/docs/reference/gio/gio-undeclared.txt"
- "_build/docs/reference/gio/gio-undocumented.txt"
- "_build/docs/reference/gio/gio-unused.txt"
- "_build/${CI_JOB_NAME}-report.xml"
- "_coverage"
@ -438,7 +452,9 @@ dist-job:
only:
- tags
script:
- meson ${MESON_COMMON_OPTIONS} --buildtype release -Dgtk_doc=true -Dman=true _build
# FIXME: Cannot use --fatal-meson-warnings here because meson warns about gtkdoc
# feature introduced in 0.52 but we only depends on 0.49.
- meson ${MESON_COMMON_OPTIONS_NO_WARNING} --buildtype release -Dgtk_doc=true -Dman=true _build
- cd _build
- ninja dist
- ninja glib-doc gobject-doc gio-doc

3
.gitlab-ci/fedora.Dockerfile
View File

@ -44,6 +44,7 @@ RUN dnf -y install \
ninja-build \
pcre-devel \
python3-dbusmock \
python3-pygments \
python3-wheel \
shared-mime-info \
systemtap-sdt-devel \
@ -55,7 +56,7 @@ RUN dnf -y install \
zlib-devel \
&& dnf clean all
RUN pip3 install meson==0.49.2
RUN pip3 install meson==0.52.1
# Enable sudo for wheel users
RUN sed -i -e 's/# %wheel/%wheel/' -e '0,/%wheel/{s/%wheel/# %wheel/}' /etc/sudoers

1
docs/reference/gio/gdbus-object-manager-example/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
gdbus-object-manager-example-overrides.txt

17
docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-docs.xml Normal file
View File

@ -0,0 +1,17 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<book lang="en" xmlns:xi="http://www.w3.org/2003/XInclude">
<part>
<title>foo</title>
<chapter>
<title>bar</title>
<xi:include href="xml/ExampleAnimal.xml"/>
<xi:include href="xml/ExampleCat.xml"/>
<xi:include href="xml/ExampleObject.xml"/>
<xi:include href="xml/ExampleObjectManagerClient.xml"/>
</chapter>
</part>
</book>

161
docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-sections.txt Normal file
View File

@ -0,0 +1,161 @@
<SECTION>
<FILE>ExampleAnimal</FILE>
<TITLE>ExampleAnimal</TITLE>
ExampleAnimal
ExampleAnimalIface
example_animal_interface_info
example_animal_override_properties
example_animal_call_poke
example_animal_call_poke_finish
example_animal_call_poke_sync
example_animal_complete_poke
example_animal_emit_jumped
example_animal_get_mood
example_animal_get_foo
example_animal_get_bar
example_animal_dup_mood
example_animal_dup_foo
example_animal_dup_bar
example_animal_set_mood
example_animal_set_foo
example_animal_set_bar
ExampleAnimalProxy
ExampleAnimalProxyClass
example_animal_proxy_new
example_animal_proxy_new_finish
example_animal_proxy_new_sync
example_animal_proxy_new_for_bus
example_animal_proxy_new_for_bus_finish
example_animal_proxy_new_for_bus_sync
ExampleAnimalSkeleton
ExampleAnimalSkeletonClass
example_animal_skeleton_new
<SUBSECTION Standard>
example_animal_get_type
example_animal_proxy_get_type
example_animal_skeleton_get_type
ExampleAnimalSkeletonPrivate
ExampleAnimalProxyPrivate
EXAMPLE_TYPE_ANIMAL
EXAMPLE_TYPE_ANIMAL_PROXY
EXAMPLE_TYPE_ANIMAL_SKELETON
EXAMPLE_ANIMAL
EXAMPLE_ANIMAL_GET_IFACE
EXAMPLE_ANIMAL_PROXY
EXAMPLE_ANIMAL_PROXY_CLASS
EXAMPLE_ANIMAL_PROXY_GET_CLASS
EXAMPLE_ANIMAL_SKELETON
EXAMPLE_ANIMAL_SKELETON_CLASS
EXAMPLE_ANIMAL_SKELETON_GET_CLASS
EXAMPLE_IS_ANIMAL
EXAMPLE_IS_ANIMAL_PROXY
EXAMPLE_IS_ANIMAL_PROXY_CLASS
EXAMPLE_IS_ANIMAL_SKELETON
EXAMPLE_IS_ANIMAL_SKELETON_CLASS
</SECTION>
<SECTION>
<FILE>ExampleCat</FILE>
<TITLE>ExampleCat</TITLE>
ExampleCat
ExampleCatIface
example_cat_interface_info
example_cat_override_properties
ExampleCatProxy
ExampleCatProxyClass
example_cat_proxy_new
example_cat_proxy_new_finish
example_cat_proxy_new_sync
example_cat_proxy_new_for_bus
example_cat_proxy_new_for_bus_finish
example_cat_proxy_new_for_bus_sync
ExampleCatSkeleton
ExampleCatSkeletonClass
example_cat_skeleton_new
<SUBSECTION Standard>
example_cat_get_type
example_cat_proxy_get_type
example_cat_skeleton_get_type
ExampleCatProxyPrivate
ExampleCatSkeletonPrivate
EXAMPLE_TYPE_CAT
EXAMPLE_TYPE_CAT_PROXY
EXAMPLE_TYPE_CAT_SKELETON
EXAMPLE_CAT
EXAMPLE_CAT_GET_IFACE
EXAMPLE_CAT_PROXY
EXAMPLE_CAT_PROXY_CLASS
EXAMPLE_CAT_PROXY_GET_CLASS
EXAMPLE_CAT_SKELETON
EXAMPLE_CAT_SKELETON_CLASS
EXAMPLE_CAT_SKELETON_GET_CLASS
EXAMPLE_IS_CAT
EXAMPLE_IS_CAT_PROXY
EXAMPLE_IS_CAT_PROXY_CLASS
EXAMPLE_IS_CAT_SKELETON
EXAMPLE_IS_CAT_SKELETON_CLASS
</SECTION>
<SECTION>
<FILE>ExampleObject</FILE>
<TITLE>ExampleObject</TITLE>
ExampleObject
ExampleObjectIface
example_object_get_animal
example_object_get_cat
example_object_peek_animal
example_object_peek_cat
ExampleObjectProxy
ExampleObjectProxyClass
example_object_proxy_new
ExampleObjectSkeleton
ExampleObjectSkeletonClass
example_object_skeleton_new
example_object_skeleton_set_animal
example_object_skeleton_set_cat
<SUBSECTION Standard>
example_object_get_type
example_object_proxy_get_type
example_object_skeleton_get_type
ExampleObjectProxyPrivate
ExampleObjectSkeletonPrivate
EXAMPLE_IS_OBJECT
EXAMPLE_IS_OBJECT_PROXY
EXAMPLE_IS_OBJECT_PROXY_CLASS
EXAMPLE_IS_OBJECT_SKELETON
EXAMPLE_IS_OBJECT_SKELETON_CLASS
EXAMPLE_OBJECT
EXAMPLE_OBJECT_GET_IFACE
EXAMPLE_OBJECT_PROXY
EXAMPLE_OBJECT_PROXY_CLASS
EXAMPLE_OBJECT_PROXY_GET_CLASS
EXAMPLE_OBJECT_SKELETON
EXAMPLE_OBJECT_SKELETON_CLASS
EXAMPLE_OBJECT_SKELETON_GET_CLASS
EXAMPLE_TYPE_OBJECT
EXAMPLE_TYPE_OBJECT_PROXY
EXAMPLE_TYPE_OBJECT_SKELETON
</SECTION>
<SECTION>
<FILE>ExampleObjectManagerClient</FILE>
<TITLE>ExampleObjectManagerClient</TITLE>
ExampleObjectManagerClient
ExampleObjectManagerClientClass
example_object_manager_client_get_proxy_type
example_object_manager_client_new
example_object_manager_client_new_finish
example_object_manager_client_new_sync
example_object_manager_client_new_for_bus
example_object_manager_client_new_for_bus_finish
example_object_manager_client_new_for_bus_sync
<SUBSECTION Standard>
example_object_manager_client_get_type
EXAMPLE_IS_OBJECT_MANAGER_CLIENT
EXAMPLE_IS_OBJECT_MANAGER_CLIENT_CLASS
EXAMPLE_OBJECT_MANAGER_CLIENT
EXAMPLE_OBJECT_MANAGER_CLIENT_CLASS
EXAMPLE_OBJECT_MANAGER_CLIENT_GET_CLASS
EXAMPLE_TYPE_OBJECT_MANAGER_CLIENT
ExampleObjectManagerClientPrivate
</SECTION>

10
docs/reference/gio/gdbus-object-manager-example/meson.build Normal file
View File

@ -0,0 +1,10 @@
gdbus_object_manager_example_doc = gnome.gtkdoc('gdbus-object-manager-example',
main_xml : 'gdbus-object-manager-example-docs.xml',
namespace : 'example',
dependencies : [libgdbus_example_objectmanager_dep],
src_dir : 'gio/tests/gdbus-object-manager-example',
scan_args : gtkdoc_common_scan_args + [
'--rebuild-types',
],
)

8
docs/reference/gio/gio-docs.xml
View File

@ -373,6 +373,14 @@
<title>Index of new symbols in 2.60</title>
<xi:include href="xml/api-index-2.60.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-62" role="2.62">
<title>Index of new symbols in 2.62</title>
<xi:include href="xml/api-index-2.62.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-64" role="2.64">
<title>Index of new symbols in 2.64</title>
<xi:include href="xml/api-index-2.64.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>

9
docs/reference/gio/meson.build
View File

@ -1,4 +1,5 @@
if get_option('gtk_doc')
subdir('gdbus-object-manager-example')
subdir('xml')
ignore_headers = [
@ -132,8 +133,6 @@ if get_option('gtk_doc')
'xdp-dbus.c',
]
# FIXME: ExampleAnimal docs aren't built
docpath = join_paths(glib_datadir, 'gtk-doc', 'html')
version_conf = configuration_data()
version_conf.set('VERSION', meson.project_version())
@ -188,6 +187,9 @@ if get_option('gtk_doc')
'gresource.xml',
'gdbus.xml',
'gdbus-codegen.xml',
gdbus_example_objectmanager_xml,
gdbus_example_objectmanager_sources,
gdbus_object_manager_example_doc,
],
expand_content_files : [
'overview.xml',
@ -207,7 +209,8 @@ if get_option('gtk_doc')
'--extra-dir=' + join_paths('gio', '..', 'glib', 'html'),
'--extra-dir=' + join_paths('gio', '..', 'gobject', 'html'),
],
install: true
install: true,
check: true,
)
endif

29
docs/reference/gio/migrating-gdbus.xml
View File

@ -241,6 +241,9 @@ on_name_acquired (GDBusConnection *connection,
</para>
</section>
<section>
<title>Generating code and docs</title>
<section id="gdbus-example-gdbus-codegen">
<title>Using gdbus-codegen</title>
@ -267,7 +270,12 @@ gdbus-codegen --interface-prefix org.gtk.GDBus.Example.ObjectManager. \
generated. Additionally, two XML files
<filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Animal</filename> and
<filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Cat</filename>
with Docbook XML are generated.
with Docbook XML are generated. For an example of what the docs look
like see <link
linkend="gdbus-interface-org-gtk-GDBus-Example-ObjectManager-Animal">the Animal D-Bus interface documentation</link>.
and
<link
linkend="gdbus-interface-org-gtk-GDBus-Example-ObjectManager-Cat">the Cat D-Bus interface documentation</link>.
</para>
<para>
While the contents of <filename>generated-code.h</filename> and
@ -276,9 +284,26 @@ gdbus-codegen --interface-prefix org.gtk.GDBus.Example.ObjectManager. \
linkend="gdbus-codegen">gdbus-codegen</link></command> manual
page, brief examples of how this generated code can be used can be found in
<xref linkend="gdbus-example-codegen-server"/>
and <xref linkend="gdbus-example-codegen-client"/>.
and <xref
linkend="gdbus-example-codegen-client"/>. Additionally, since
the generated code has 100% gtk-doc coverage, see
#ExampleAnimal, #ExampleCat, #ExampleObject and
#ExampleObjectManagerClient pages for documentation.
</para>
<example id="gdbus-example-codegen-server"><title>Server-side application using generated code</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../gdbus-example-objectmanager-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
<example id="gdbus-example-codegen-client"><title>Client-side application using generated code</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../gdbus-example-objectmanager-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
</section>
<xi:include href="../../../../gio/tests/gdbus-object-manager-example/objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Animal.xml"/>
<xi:include href="../../../../gio/tests/gdbus-object-manager-example/objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Cat.xml"/>
<xi:include href="../gdbus-object-manager-example/xml/ExampleAnimal.xml"/>
<xi:include href="../gdbus-object-manager-example/xml/ExampleCat.xml"/>
<xi:include href="../gdbus-object-manager-example/xml/ExampleObject.xml"/>
<xi:include href="../gdbus-object-manager-example/xml/ExampleObjectManagerClient.xml"/>
</section>
</chapter>

3
docs/reference/glib/meson.build
View File

@ -88,7 +88,8 @@ if get_option('gtk_doc')
fixxref_args: [
'--html-dir=' + docpath,
],
install: true)
install: true,
check: true)
endif
if get_option('man')

3
docs/reference/gobject/meson.build
View File

@ -50,7 +50,8 @@ if get_option('gtk_doc')
'--html-dir=' + docpath,
'--extra-dir=' + join_paths('gobject', '..', 'glib', 'html'),
],
install: true
install: true,
check: true,
)
endif

7
docs/reference/meson.build
View File

@ -45,9 +45,14 @@ gtkdoc_common_scan_args = [
]
if get_option('gtk_doc')
if not meson.version().version_compare('>=0.52.0')
error('Building documentation requires Meson >= 0.52.0.')
endif
# Check we have the minimum gtk-doc version required. Older versions won't
# generate correct documentation.
dependency('gtk-doc', version : '>=1.32')
dependency('gtk-doc', version : '>=1.32',
fallback : ['gtk-doc', 'dummy_dep'],
default_options : ['tests=false'])
endif
subdir('gio')

6
gio/tests/gdbus-object-manager-example/meson.build
View File

@ -1,6 +1,7 @@
# FIXME: set UNINSTALLED_GLIB_{SRC|BUILD}DIR=top_{src|build}dir ?
gdbus_example_objectmanager_xml = files('gdbus-example-objectmanager.xml')
gdbus_example_objectmanager_generated = custom_target('objectmanager-gen',
input : ['gdbus-example-objectmanager.xml'],
input : gdbus_example_objectmanager_xml,
output : ['objectmanager-gen.h',
'objectmanager-gen.c',
'objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Animal.xml',
@ -23,4 +24,5 @@ libgdbus_example_objectmanager = library('gdbus-example-objectmanager',
libgdbus_example_objectmanager_dep = declare_dependency(
sources : gdbus_example_objectmanager_generated[0],
link_with : libgdbus_example_objectmanager)
link_with : libgdbus_example_objectmanager,
dependencies : [libgio_dep])

5
gio/tests/meson.build
View File

@ -431,6 +431,11 @@ test_extra_programs += {
},
}
gdbus_example_objectmanager_sources = files(
'gdbus-example-objectmanager-client.c',
'gdbus-example-objectmanager-server.c',
)
if cc.get_id() != 'msvc' and cc.get_id() != 'clang-cl'
test_extra_programs += {
# These three are manual-run tests because they need a session bus but don't bring one up themselves

4
glib/gmacros.h
View File

@ -1101,9 +1101,11 @@
* @struct_type: a structure type, e.g. #GOutputVector
* @member: a field in the structure, e.g. `size`
*
* Returns: the size of @member in the struct definition without having a
* Returns the size of @member in the struct definition without having a
* declared instance of @struct_type.
*
* Returns: the size of @member in bytes.
*
* Since: 2.64
*/
#define G_SIZEOF_MEMBER(struct_type, member) \

1
meson.build
View File

@ -353,7 +353,6 @@ endforeach
# Compiler flags
if cc.get_id() == 'gcc' or cc.get_id() == 'clang'
warning_c_args = [
'-Wall',
'-Wduplicated-branches',
'-Wimplicit-fallthrough',
'-Wmisleading-indentation',

4
subprojects/gtk-doc.wrap Normal file
View File

@ -0,0 +1,4 @@
[wrap-git]
directory=gtk-doc
url=https://gitlab.gnome.org/GNOME/gtk-doc.git
revision=master