These symbols are documented in the {glib,gio}-{unix,win32}
documentation builds, and shouldn’t be duplicated in the main
documentation. It’s a historical (and unavoidable) accident that those
symbols are in the main GIR files.
If we don’t hide the symbols from the main docs build, we now run into
the problem of the `GioUnix` namespace not being known to gi-docgen
while building the `Gio` docs. This is because of the previous two
commits, which ported more of the `gunixmounts` documentation to
gi-docgen syntax. I don’t know of another way to fix this, other than to
hide the `GioUnix` symbols from the `Gio` docs build.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3250
Let’s not go with SHOUTY UNIX or quiet unix, let’s just call it what
Wikipedia calls it (https://en.wikipedia.org/wiki/Unix).
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
They need a `GUnixMountMonitor` to give valid timestamps, and if you
have one of those then you might as well listen to its signals anyway.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Fixes: #3569
If only someone would go ahead and invent a whole section of the list of
HTTP status codes which could be used to inform a client of where a
document has been moved to.
For the sake of argument, let’s say it could be status codes 300–399,
since they appear to be completely unused at the moment.
😩
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
This used to happen consistently before !4290, but that MR changed it so
that `data` could be non-`NULL` if `size == 0` if the new inline code
path is taken.
While users of `GBytes` shouldn’t be dereferencing the data if the
bytes’ length is zero, it’s definitely safer to make sure the data is
`NULL` in that case.
This shouldn’t break the expectations of any third party code because
it’s restoring the behaviour from before !4290.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Fixes: #3562
The documentation for GLib and Gio contains a number of documentation
comment blocks where a parameter reference (e.g. `@err`) is also
discussed in its dereferenced pointer form, which is generally
annotated as `*@err`. This inevitably confuses the MarkDown parser,
which sees the `*` as the beginning of an italicized text span.
To avoid this, replace all `*@foo` with <code>`*foo`</code>, which
loses the `@`-sigil linking it to the `@foo` parameter, but formats
correctly in the rendered documentation. (`@foo` is automatically
formatted like <code>`foo`</code>, so the resulting appearance in
the docs is as intended.)
`@filename@` expands to the (absolute or relative) path from the
build directory to the source directory, which can be rather verbose.
In practice Meson usually (always?) generates a relative path, but
even so, the resulting installed header is not necessarily reproducible
if using different build directories outside the source directory.
We don't really need a full path here anyway: the basename is enough
of a hint to point a reader towards the file where the underlying
enum was defined.
Signed-off-by: Simon McVittie <smcv@collabora.com>
The deprecated construct '@0@'.format(h) (where h is a file object)
expanded to the filename relative to the project root, which in this
particular case happens to be what we wanted:
`--c-include=gio/gunixmounts.h` resulted in a recommendation to
`#include <gio/gunixmounts.h>` and so on. Replacing it with
h.full_path() resulted in GIR XML and documentation that recommended
constructs like `#include </home/me/src/glib/gio/gunixmounts.h>`,
which is not what was intended (and caused new differences between
different architectures' Gio-2.0.gir on multiarch systems, which is
how I discovered this).
Hard-coding `gio/` and appending the basename of the header seems like
the simplest non-deprecated spelling that will do what we wanted.
Fixes: 51e3e7d9 "build: Bump Meson dependency to 1.4.0"
Resolves: https://gitlab.gnome.org/GNOME/glib/-/issues/3564
Signed-off-by: Simon McVittie <smcv@collabora.com>
This tests the C++ version of g_win32_clear_com() as there are some
COM interfaces that are only available in C++, such as DirectWrite from
the headers shipped with the Windows SDK.
This mimicks the test for the same function in glib/tests/win32.c but
done in a C++ fashion.
This is quite similar in concept to what g_clear_object() does, except
that is meant to deal with Windows COM objects. Note that there is a
separate C++ version available for this as there are COM interfaces that
are available in C++ only, such as DirectWrite that is shipped with the
Windows SDK (albeit a C interface is provided with the mingw-w64
toolchain.
This will call `->Release()` on the non-NULL COM object referenced by its
pointer and sets the COM object to NULL; if the pointer refers to a
NULL COM object, this is a no-op.
None of these comments have been ported to gi-docgen format properly
yet, but let’s at least fix the backslash escaping so that
`G_DIR_SEPARATOR_S` can be documented usefully.
A full port of this file to gi-docgen format can happen in future.
Spotted on
https://discourse.gnome.org/t/escaped-char-in-glib-dir-separator-s-doc/25607.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
This will allow us to test that it actually still works, which is
important for being able to make releases, because once we push a tag,
there’s no going back. The release can’t happen if `dist-job` then fails
on that tag.
Sigh.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
If `-Ddocumentation=true` is specified without
`-Dintrospection=enabled`, warn the user. They might expect the
documentation to be built, but it won’t.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
This means that the documentation can actually be generated, which was
broken before. Building the documentation requires `enable_gir`.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
