This makes it a little easier to link to in the generated documentation,
and separates it from the section above.
Link to the heading from the documentation for
`G_DEFINE_EXTENDED_ERROR`.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
At this point, if `dest` is non-`NULL` then we can guarantee
`*dest != NULL` due to `g_propagate_error()` succeeding.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Factor out the GError creation to a common function. When adding a
support for extended error types, this will limit the number of places
where these errors are allocated.
It’s confusing and often doesn’t help the user. Match the error code and
come up with a more UI-appropriate error message.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
Prevent the situation where errno is set by function A, then function B
is called (which is typically _(), but could be anything else) and it
overwrites errno, then errno is checked by the caller.
errno is a horrific API, and we need to be careful to save its value as
soon as a function call (which might set it) returns. i.e. Follow the
pattern:
int errsv, ret;
ret = some_call_which_might_set_errno ();
errsv = errno;
if (ret < 0)
puts (strerror (errsv));
This patch implements that pattern throughout GLib. There might be a few
places in the test code which still use errno directly. They should be
ported as necessary. It doesn’t modify all the call sites like this:
if (some_call_which_might_set_errno () && errno == ESOMETHING)
since the refactoring involved is probably more harmful than beneficial
there. It does, however, refactor other call sites regardless of whether
they were originally buggy.
https://bugzilla.gnome.org/show_bug.cgi?id=785577
All glib/*.{c,h} files have been processed, as well as gtester-report.
12 of those files are not licensed under LGPL:
gbsearcharray.h
gconstructor.h
glibintl.h
gmirroringtable.h
gscripttable.h
gtranslit-data.h
gunibreak.h
gunichartables.h
gunicomp.h
gunidecomp.h
valgrind.h
win_iconv.c
Some of them are generated files, some are licensed under a BSD-style
license and win_iconv.c is in the public domain.
Sub-directories inside glib/:
deprecated/: processed in a previous commit
glib-mirroring-tab/: already LGPLv2.1+
gnulib/: not modified, the code is copied from gnulib
libcharset/: a copy
pcre/: a copy
tests/: processed in a previous commit
https://bugzilla.gnome.org/show_bug.cgi?id=776504
There are a few places where commit 18a33f72 replaced valid (nullable)
(optional) annotations with just (optional). That has a different
meaning.
(nullable) (optional) can only be applied to gpointer* parameters, and
means that both the gpointer* and returned gpointer can be NULL. i.e.
The caller can pass in NULL to ignore the return value; and the returned
value can be NULL.
(optional) can be applied to anything* parameters, and means that the
anything* can be NULL. i.e. The caller can pass in NULL to ignore the
return value. The return value cannot be NULL.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
If we have an input parameter (or return value) we need to use (nullable).
However, if it is an (inout) or (out) parameter, (optional) is sufficient.
It looks like (nullable) could be used for everything according to the
Annotation documentation, but (optional) is more specific.
Add various (nullable) and (optional) annotations which were missing
from a variety of functions. Also port a couple of existing (allow-none)
annotations in the same files to use (nullable) and (optional) as
appropriate instead.
Secondly, add various (not nullable) annotations as needed by the new
default in gobject-introspection of marking gpointers as (nullable). See
https://bugzilla.gnome.org/show_bug.cgi?id=729660.
This includes adding some stub documentation comments for the
assertion macro error functions, which weren’t previously documented.
The new comments are purely to allow for annotations, and hence are
marked as (skip) to prevent the symbols appearing in the GIR file.
https://bugzilla.gnome.org/show_bug.cgi?id=719966
Despite knowing about GError, there are multiple cases where developers
have still used traditional numeric error codes, and then got themselves
into a mess about bindability and generation of error messages.
Try and avoid this by including a brief paragraph on the benefits of
GError over EINVAL-style error codes.
https://bugzilla.gnome.org/show_bug.cgi?id=743011
This means that the top of the documentation can link forward to this
important section, and random people on the internet can link directly
to it on developer.gnome.org.
https://bugzilla.gnome.org/show_bug.cgi?id=743011
• Clarify that GError** parameters are for the return of _newly
allocated_ GError*s.
• Clarify that errors may need to be checked for explicitly if the
return value of a function doesn’t reliably indicate them.
https://bugzilla.gnome.org/show_bug.cgi?id=741779
Since we are no longer using sgml mode, using /* */ to
escape block comments inside examples does not work anymore.
Switch to using line comments with //
In particular, it is not incorrect to g_return_if_fail (..., FALSE)
in a function returning a "success" gboolean and a GError: "failure to
meet the preconditions is an error" takes precedence over the
GError documentation's guarantee that the error will be set on failure.
Bug: https://bugzilla.gnome.org/show_bug.cgi?id=660809
Reviewed-by: Emmanuele Bassi
Since all element markup is now gone from the doc comments,
we can turn off the gtk-doc sgml mode, which means that from
now on, docbook markup is no longer allowed in doc comments.
To make this possible, we have to replace all remaining
entities in doc comments by their replacement text, & -> &
and so on.
Even though we can't always make no-leak guarantees when g_warning()
in this case we're testing this behavior in tests, and it would be
good to be able to valgrind this.
https://bugzilla.gnome.org/show_bug.cgi?id=711751
This allows compilation with clang without errors, even when
-Wformat-nonliteral is active (as long as there are no real cases of
non literal formatting).
https://bugzilla.gnome.org/show_bug.cgi?id=691608
Neither of those usages is valid, but there's a lot of use of 0 as a
domain "in the wild", so we can't g_return_if_fail yet.
Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Bug: https://bugzilla.gnome.org/show_bug.cgi?id=660371
