These rules are not new, they’ve been around for a long time and are
needed to allow introspection machinery to be able to work reliably and
deterministically.
Unfortunately, they have not been documented canonically in one place
before.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
The `gi-docgen` tool is not designed to be used like that. In
particular, when nesting documentation directories, the generated
`*.devhelp2` files (needed by Devhelp to show the documentation) are
nested one directory level too deep for Devhelp to find them, and hence
are useless, and the documentation doesn’t show up in this common
documentation viewer.
So, change the installed documentation directory hierarchy:
* `${PREFIX}/share/doc/glib-2.0/gio` → `${PREFIX}/share/doc/gio-2.0`
* `${PREFIX}/share/doc/glib-2.0/glib-unix` →
`${PREFIX}/share/doc/glib-unix-2.0`
* `${PREFIX}/share/doc/glib-2.0/gobject` →
`${PREFIX}/share/doc/gobject-2.0`
* etc.
* `${PREFIX}/share/doc/glib-2.0/glib` → `${PREFIX}/share/doc/glib-2.0`
This is going to seem like pointless churn (the contents of the
documentation have not changed), and packagers may mourn the split of
content in `/usr/share/doc` from `/usr/share/doc/${package_name}` to
`/usr/share/doc/${pkg_config_id}` instead, but that seems to be the best
approach to fix this issue in GLib. gi-docgen’s behaviour does feel
fairly consistent and correct with the rest of how it works (single
output directory).
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Fixes: #3287
This is nowhere near a complete check-through and gi-docgenification of
the signals docs, just a few bits I was looking at anyway.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3250
Seems no point in keeping them separate. It doesn’t seem to matter if
they contain entries which are unused for a particular docs build.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Now that the reference documentation uses gi-docgen, it's more
troublesome to generate in less standard build scenarios like
cross-compiling.
In distributions like Debian, reference documentation is generally
packaged separately (in libglib2.0-doc in Debian's case), but man pages
are generally packaged alongside the executables themselves (in the
libglib2.0-bin and libglib2.0-dev-bin packages, in Debian's case). We
can exclude the reference documentation when cross-compiling, but ideally
we would like the man pages to still be built, so that a cross-compiled
libglib2.0-bin or libglib2.0-dev-bin package has the same content as a
native build.
Signed-off-by: Simon McVittie <smcv@debian.org>
They are now installed to (e.g.)
`${prefix}/share/doc/glib-2.0/{glib,gmodule,gobject,gio}/index.html`.
We might want to drop one level of nesting out of that, but for the
moment I thought I’d keep it in so we can disambiguate by installed
major version.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
So they are consistent with the way we’re building man pages in other
projects, and because some people are allergic to XML.
This changes the build-time dependencies from `xsltproc` to `rst2man`,
and also takes the opportunity to change the `-Dman` Meson option from a
boolean to a feature (so you should use `-Dman-pages={enabled,disabled}`
now, rather than `-Dman={true,false}`).
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
The GIR files are now built by GLib itself, so they will be in the build
directories of each sub-library, except for GLib-2.0 which is built
alongside GObject-2.0.
On CHERI-enabled systems we use uintptr_t as the underlying storage for
GType and therefore casting to gsize strips the upper bits from a pointer.
Fix this by casting via uintptr_t instead and introduce a new set of
macros to convert between GType and pointers.
It needs to be in a separate page because it’s all macros and they have
no type/class associated with them.
Signed-off-by: Philip Withnall <philip@tecnocode.co.uk>
Helps: #3037
Gate the API reference on the availability of the introspection data as
well, so we don't accidentally try and generate the documentation
without a description of our API.
As we start moving documentation over from gtk-doc to gi-docgen, the
gtk-doc coverage is going to go down and things are going to start
breaking. That’s OK; we don’t need to test it any more.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Helps: #3037
The files here are copied from the docs-gtk-org
branch of gtk.
This adds gi-docgen to the CI Dockerfiles and ensures the new versions
(including the OS upgrades from the previous commit) are used during CI.
Helps: #3037
The introspection scanner cannot deal very well with function pointers
into a plain structure. In order to document the various function
pointers in GTypeValueTable we need to create typed callbacks, and
use them to replace the anonymous function pointers inside the
structure. This not only allows us to properly document the function
pointers, but it also allows us to annotate the arguments and return
value of those function pointers.
See also: https://gitlab.gnome.org/GNOME/gobject-introspection/-/merge_requests/400#note_1721707
GTK lost it's '+' suffix back in 2019, according to
<https://mail.gnome.org/archives/gtk-devel-list/2019-February/msg00000.html>
This commit can be re-generated with:
git grep -l GTK+ \
| grep -v -e ^NEWS -e ^glib/tests/collate.c \
| xargs sed -i 's/GTK+/GTK/g'
Most of the changes are in comments and documentation.
The documentation previously implicitly said in a few places that
interfaces are classed, but reading through the implementation of
`GType`, I don’t think they are. If they were, the registration of the
fundamental `G_TYPE_INTERFACE` in `gobject_init()` would specify
`G_TYPE_FLAG_CLASSED`. It only specifies `G_TYPE_FLAG_DERIVABLE`.
I think this makes sense, because you can’t subclass an interface.
Subclassing is a key property of being classed.
Tweak the `GType` tutorial to remove that implicit statement, and expand
the documentation for `G_TYPE_IS_CLASSED`.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Fixes: #252
This can be used to mark entire types as deprecated,
and trigger a warning when they are instantiated
and `G_ENABLE_DIAGNOSTIC=1` is set in the environment.
There's currently no convenient macros for defining
types with the new flag, but you can do:
```c
_G_DEFINE_TYPE_EXTENDED_BEGIN (GtkAppChooserWidget,
gtk_app_chooser_widget,
GTK_TYPE_WIDGET,
G_TYPE_FLAG_DEPRECATED)
...
_G_DEFINE_TYPE_EXTENDED_END ()
```
Includes a unit test by Philip Withnall.
There is currently no `dllimport` attribute on any of our function,
which prevents MSVC to optimize function calls.
To fix that issue, we need to redeclare all our visibility macros for
each of our libraries, because when compiling e.g. GIO code, we need
dllimport in GLIB headers and dllexport in GIO headers. That means they
cannot use the same GLIB_AVAILABLE_* macro.
Since that's a lot of boilerplate to copy/paste after each version bump,
this MR generate all those macros using a python script.
Also simplify the meson side by using `gnu_symbol_visibility : 'hidden'`
keyword argument instead of passing the cflag manually.
This leaves only API index to add manually into glib-docs.xml when
bumping GLib version. That file cannot be generated because Meson does
not allow passing a buit file to gnome.gtkdoc()'s main_xml kwarg
unfortunately.
We should mention glib-mkenums in the documentation for
G_DEFINE_ENUM_TYPE and G_DEFINE_FLAGS_TYPE.
We should also mention the macros in the documentation for glib-mkenums.
This way, developers can choose the most appropriate tool for their use
case.
