glib: Add missing (nullable) and (optional) annotations

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

1 files changed, 32 insertions, 6 deletions

diff --git a/glib/gslice.c b/glib/gslice.c
index 0563d8092..9022062ac 100644
--- a/glib/gslice.c
+++ b/glib/gslice.c
@@ -873,7 +873,11 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
  * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE]
  * environment variable.
  *
- * Returns: a pointer to the allocated block, cast to a pointer to @type
+ * This can never return %NULL as the minimum allocation size from
+ * `sizeof (@type)` is 1 byte.
+ *
+ * Returns: (not nullable): a pointer to the allocated block, cast to a pointer
+ *    to @type
  *
  * Since: 2.10
  */
@@ -892,13 +896,19 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
  * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
  * environment variable.
  *
+ * This can never return %NULL as the minimum allocation size from
+ * `sizeof (@type)` is 1 byte.
+ *
+ * Returns: (not nullable): a pointer to the allocated block, cast to a pointer
+ *    to @type
+ *
  * Since: 2.10
  */
 
 /**
  * g_slice_dup:
  * @type: the type to duplicate, typically a structure name
- * @mem: the memory to copy into the allocated block
+ * @mem: (not nullable): the memory to copy into the allocated block
  *
  * A convenience macro to duplicate a block of memory using
  * the slice allocator.
@@ -910,7 +920,10 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
  * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
  * environment variable.
  *
- * Returns: a pointer to the allocated block, cast to a pointer to @type
+ * This can never return %NULL.
+ *
+ * Returns: (not nullable): a pointer to the allocated block, cast to a pointer
+ *    to @type
  *
  * Since: 2.14
  */
@@ -929,6 +942,8 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
  * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
  * [`G_SLICE`][G_SLICE] for related debugging options.
  *
+ * If @mem is %NULL, this macro does nothing.
+ *
  * Since: 2.10
  */
 
@@ -947,6 +962,8 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
  * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
  * [`G_SLICE`][G_SLICE] for related debugging options.
  *
+ * If @mem_chain is %NULL, this function does nothing.
+ *
  * Since: 2.10
  */
 
@@ -964,7 +981,8 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
  * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
  * environment variable.
  *
- * Returns: a pointer to the allocated memory block
+ * Returns: a pointer to the allocated memory block, which will be %NULL if and
+ *    only if @mem_size is 0
  *
  * Since: 2.10
  */
@@ -1022,7 +1040,8 @@ g_slice_alloc (gsize mem_size)
  * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE]
  * environment variable.
  *
- * Returns: a pointer to the allocated block
+ * Returns: a pointer to the allocated block, which will be %NULL if and only
+ *    if @mem_size is 0
  *
  * Since: 2.10
  */
@@ -1043,7 +1062,10 @@ g_slice_alloc0 (gsize mem_size)
  * Allocates a block of memory from the slice allocator
  * and copies @block_size bytes into it from @mem_block.
  *
- * Returns: a pointer to the allocated memory block
+ * @mem_block must be non-%NULL if @block_size is non-zero.
+ *
+ * Returns: a pointer to the allocated memory block, which will be %NULL if and
+ *    only if @mem_size is 0
  *
  * Since: 2.14
  */
@@ -1070,6 +1092,8 @@ g_slice_copy (gsize         mem_size,
  * can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment
  * variable, also see [`G_SLICE`][G_SLICE] for related debugging options.
  *
+ * If @mem_block is %NULL, this function does nothing.
+ *
  * Since: 2.10
  */
 void
@@ -1130,6 +1154,8 @@ g_slice_free1 (gsize    mem_size,
  * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
  * [`G_SLICE`][G_SLICE] for related debugging options.
  *
+ * If @mem_chain is %NULL, this function does nothing.
+ *
  * Since: 2.10
  */
 void