docs: Move some documentation comments from docs.c to their symbols

It would be nice if docs.c eventually went away — it’s more maintainable
for documentation comments to be next to the definition of the symbols
they document.

Move a few from docs.c, based on what I’ve been modifying recently.

The documentation comments are unchanged apart from fixing an argument
name for G_ALIGNOF.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

glib/docs.c

@@ -1845,23 +1845,6 @@
  * arrays or arrays on the stack.
  */
 
-/**
- * G_ALIGNOF
- * @a: a type-name
- *
- * Return the minimal alignment required by the platform ABI for values of the given
- * type. The address of a variable or struct member of the given type must always be
- * a multiple of this alignment. For example, most platforms require int variables
- * to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms.
- *
- * Note this is not necessarily the same as the value returned by GCC’s
- * `__alignof__` operator, which returns the preferred alignment for a type.
- * The preferred alignment may be a stricter alignment than the minimal
- * alignment.
- *
- * Since: 2.60
- */
-
 /* Miscellaneous Macros {{{1 */
 
 /**
@@ -1873,20 +1856,6 @@
  * needed so often by application programmers.
  */
 
-/**
- * G_INLINE_FUNC:
- *
- * This macro used to be used to conditionally define inline functions
- * in a compatible way before this feature was supported in all
- * compilers.  These days, GLib requires inlining support from the
- * compiler, so your GLib-using programs can safely assume that the
- * "inline" keywork works properly.
- *
- * Never use this macro anymore.  Just say "static inline".
- *
- * Deprecated: 2.48: Use "static inline" instead
- */
-
 /**
  * G_STMT_START:
  *

glib/gmacros.h

@@ -82,6 +82,20 @@
 
 #undef G_INLINE_DEFINE_NEEDED
 
+/**
+ * G_INLINE_FUNC:
+ *
+ * This macro used to be used to conditionally define inline functions
+ * in a compatible way before this feature was supported in all
+ * compilers.  These days, GLib requires inlining support from the
+ * compiler, so your GLib-using programs can safely assume that the
+ * "inline" keywork works properly.
+ *
+ * Never use this macro anymore.  Just say "static inline".
+ *
+ * Deprecated: 2.48: Use "static inline" instead
+ */
+
 #ifndef G_DISABLE_DEPRECATED
 /* For historical reasons we need to continue to support those who
  * define G_IMPLEMENT_INLINES to mean "don't implement this here".
@@ -831,6 +845,22 @@
  * https://gitlab.gnome.org/GNOME/glib/merge_requests/538/diffs#note_390790.
  */
 
+/**
+ * G_ALIGNOF
+ * @type: a type-name
+ *
+ * Return the minimal alignment required by the platform ABI for values of the given
+ * type. The address of a variable or struct member of the given type must always be
+ * a multiple of this alignment. For example, most platforms require int variables
+ * to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms.
+ *
+ * Note this is not necessarily the same as the value returned by GCC’s
+ * `__alignof__` operator, which returns the preferred alignment for a type.
+ * The preferred alignment may be a stricter alignment than the minimal
+ * alignment.
+ *
+ * Since: 2.60
+ */
 #if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L && !defined(__cplusplus)
 #define G_ALIGNOF(type) _Alignof (type)
 #else

glib/gtestutils.c

@@ -347,28 +347,6 @@
  * Since: 2.16
  */
 
-/**
- * GTestTrapFlags:
- * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to
- *     `/dev/null` so it cannot be observed on the console during test
- *     runs. The actual output is still captured though to allow later
- *     tests with g_test_trap_assert_stdout().
- * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to
- *     `/dev/null` so it cannot be observed on the console during test
- *     runs. The actual output is still captured though to allow later
- *     tests with g_test_trap_assert_stderr().
- * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the
- *     child process is shared with stdin of its parent process.
- *     It is redirected to `/dev/null` otherwise.
- *
- * Test traps are guards around forked tests.
- * These flags determine what traps to set.
- *
- * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(),
- * which is deprecated. g_test_trap_subprocess() uses
- * #GTestSubprocessFlags.
- */
-
 /**
  * GTestSubprocessFlags:
  * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child

glib/gtestutils.h

@@ -338,6 +338,27 @@ void    g_test_queue_destroy            (GDestroyNotify destroy_func,
 #define g_test_queue_unref(gobject)     g_test_queue_destroy (g_object_unref, gobject)
 
 #ifndef G_DISABLE_DEPRECATED
+/**
+ * GTestTrapFlags:
+ * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to
+ *     `/dev/null` so it cannot be observed on the console during test
+ *     runs. The actual output is still captured though to allow later
+ *     tests with g_test_trap_assert_stdout().
+ * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to
+ *     `/dev/null` so it cannot be observed on the console during test
+ *     runs. The actual output is still captured though to allow later
+ *     tests with g_test_trap_assert_stderr().
+ * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the
+ *     child process is shared with stdin of its parent process.
+ *     It is redirected to `/dev/null` otherwise.
+ *
+ * Test traps are guards around forked tests.
+ * These flags determine what traps to set.
+ *
+ * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(),
+ * which is deprecated. g_test_trap_subprocess() uses
+ * #GTestSubprocessFlags.
+ */
 typedef enum {
   G_TEST_TRAP_SILENCE_STDOUT    = 1 << 7,
   G_TEST_TRAP_SILENCE_STDERR    = 1 << 8,