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

Various fixes to make gtkdoc-check pass on glib

See merge request GNOME/glib!978

.gitlab-ci.yml

@@ -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

.gitlab-ci/fedora.Dockerfile

@@ -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

docs/reference/gio/gdbus-object-manager-example/.gitignore

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

docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-docs.xml

@@ -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>

docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-sections.txt

@@ -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>

docs/reference/gio/gdbus-object-manager-example/meson.build

@@ -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',
+  ],
+)
+

docs/reference/gio/gio-docs.xml

@@ -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>
 

docs/reference/gio/meson.build

@@ -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
 

docs/reference/gio/migrating-gdbus.xml

@@ -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>

docs/reference/glib/meson.build

@@ -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')

docs/reference/gobject/meson.build

@@ -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
 

docs/reference/meson.build

@@ -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')

gio/tests/gdbus-object-manager-example/meson.build

@@ -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])

gio/tests/meson.build

@@ -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

glib/gmacros.h

@@ -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) \

meson.build

@@ -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',

subprojects/gtk-doc.wrap

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