Merge branch 'old-txt-docs' into 'main'

docs: Update/Drop txt documents from docs directory

See merge request GNOME/glib!3408

docs/debugging.txt

@@ -1,38 +0,0 @@
-
-Traps (G_BREAKPOINT) and traces for the debugging
-=================================================
-
-Some code portions contain trap variables that can be set during
-debugging time if G_ENABLE_DEBUG has been defined upon compilation
-(use the --buildtype=debug option to configure for this, macros.txt
-covers more details).
-Such traps lead to immediate code halts to examine the current
-program state and backtrace.
-Currently, the following trap variables exist:
-
-static volatile gulong g_trap_free_size;
-static volatile gulong g_trap_realloc_size;
-static volatile gulong g_trap_malloc_size;
-	If set to a size > 0, g_free(), g_realloc() and g_malloc()
-	respectively, will be intercepted if the size matches the
-	size of the corresponding memory block to free/reallocate/allocate.
-	This will only work with g_mem_set_vtable (glib_mem_profiler_table)
-	upon startup though, because memory profiling is required to match
-	on the memory block sizes.
-static volatile GObject *g_trap_object_ref;
-	If set to a valid object pointer, ref/unref will be intercepted
-	with G_BREAKPOINT ();
-static volatile gpointer *g_trap_instance_signals;
-static volatile gpointer *g_trace_instance_signals;
-       If set to a valid instance pointer, debugging messages
-       will be spewed about emissions of signals on this instance.
-       For g_trap_instance_signals matches, the emissions will
-       also be intercepted with G_BREAKPOINT ();
-
-Environment variables for debugging
-===================================
-When G_ENABLE_DEBUG was defined upon compilation, the GObject library 
-supports an environment variable GOBJECT_DEBUG that can be set to a
-combination of the flags passed in to g_type_init() (currently
-"objects" and "signals") to trigger debugging messages about
-object bookkeeping and signal emissions during runtime.

docs/macros.md

@@ -0,0 +1,73 @@
+GLib's configure options and corresponding macros
+=================================================
+
+The following Meson configure options will result in certain macros or options
+being defined at build time:
+
+`--buildtype={plain,release,minsize,custom}`
+ : No special macros or options
+`--buildtype={debug,debugoptimized}` (`debugoptimized` is the default)
+ : `-DG_ENABLE_DEBUG -g`
+`-Dglib_debug=disabled`
+ : Omits `G_ENABLE_DEBUG` when implied by `--buildtype`/`-Ddebug`
+`-Dglib_debug=enabled`
+ : Defines `G_ENABLE_DEBUG` regardless of `--buildtype`/`-Ddebug`
+`-Dglib_asserts=false`
+ : `-DG_DISABLE_ASSERT`
+`-Dglib_checks=false`
+ : `-DG_DISABLE_CHECKS`
+
+Besides these, there are some local feature specific options, but the main
+focus here is to concentrate on macros that affect overall GLib behaviour
+and/or third party code.
+
+
+GLib's internal and global macros
+=================================
+
+`G_DISABLE_ASSERT`
+---
+
+The `g_assert()` and `g_assert_not_reached()` macros become non-functional
+with this define. The motivation is to speed up end-user apps by
+avoiding expensive checks.
+
+This macro can affect third-party code. Defining it when building GLib
+will only disable the assertion macros for GLib itself, but third-party code
+that passes `-DG_DISABLE_ASSERT` to the compiler in its own build
+will end up with the non-functional variants after including `glib.h`
+as well.
+
+Note: Code inside the assertion macros should not have side effects
+that affect the operation of the program, as they may get compiled out.
+
+`G_DISABLE_CHECKS`
+---
+
+This macro is similar to `G_DISABLE_ASSERT`, it affects third-party
+code as mentioned above and the note about `G_DISABLE_ASSERT` applies
+too.
+
+The macros that become non-functional here are `g_return_if_fail()`,
+`g_return_val_if_fail()`, `g_return_if_reached()` and
+`g_return_val_if_reached()`.
+
+This macro also switches off certain checks in the GSignal code.
+
+`G_ENABLE_DEBUG`
+---
+
+Quite a bit of additional debugging code is compiled into GLib when this
+macro is defined, and since it is a globally visible define, third-party code
+may be affected by it similarly to `G_DISABLE_ASSERT`.
+
+The additional code executed/compiled for this macro currently includes the
+following, but this is not an exhaustive list:
+ - extra validity checks for `GDate`
+ - breakpoint abortion for fatal log levels in `gmessages.c` instead of
+   plain `abort()` to allow debuggers trapping and overriding them
+ - added verbosity of `gscanner.c` to catch deprecated code paths
+ - added verbosity of `gutils.c` to catch deprecated code paths
+ - object and type bookkeeping in `gobject.c`
+ - extra validity checks in `gsignal.c`
+ - support for tracking still-alive `GTask`s

docs/macros.txt

@@ -1,58 +0,0 @@
-GLib's configure options and corresponding macros
-=================================================
-
---buildtype={plain,release,minsize,custom}
-	none
---buildtype={debug,debugoptimized}	[debugoptimized is the default]
-	-DG_ENABLE_DEBUG -g
--Dglib_debug=disabled
-	Omits G_ENABLE_DEBUG when implied by --buildtype/-Ddebug
--Dglib_debug=enabled
-	Defines G_ENABLE_DEBUG regardless of --buildtype/-Ddebug
--Dglib_asserts=false
-	-DG_DISABLE_ASSERT
--Dglib_checks=false
-	-DG_DISABLE_CHECKS
-
-Besides these, there are some local feature specific options, but my main
-focus here is to concentrate on macros that affect overall GLib behaviour
-and/or third party code.
-
-
-Notes on GLib's internal and global macros
-==========================================
-
-G_DISABLE_ASSERT
-	The g_assert() and g_assert_not_reached() become non-functional
-	with this define. The motivation is to speed up end-user apps by
-	avoiding expensive checks.
-	This macro can affect third-party code. Defining it when building GLib
-	will only disable the assertion macros for GLib itself, but third-party code
-	that passes -DG_DISABLE_ASSERT to the compiler upon its own build
-	will end up with the non-functional variants after including glib.h
-	as well.
-	NOTE: Code inside the assertion macros should not have side effects
-	that affect the operation of the program.
-G_DISABLE_CHECKS
-	This macro is similar to G_DISABLE_ASSERT, it affects third-party
-	code as mentioned above and the NOTE about G_DISABLE_ASSERT applies
-	too. The macros that become non-functional here are
-	g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
-	g_return_val_if_reached().
-	Additionally the glib_mem_profiler_table and g_mem_profile() from
-	gmem.h become non-functional if this macro is supplied.
-	This macro also switches off certain checks in the GSignal code.
-G_ENABLE_DEBUG
-	Quite a bit of additional debugging code is compiled into GLib for this
-	macro, and since it is a globally visible define, third-party code may
-	be affected by it similar to G_DISABLE_ASSERT.
-	The additional code executed/compiled for this macro currently involve:
-	- extra validity checks for GDate
-	- memory profiling traps in gmem.c (consult debugging.txt for details)
-	- BREAKPOINT abortion for fatal log levels in gmessage.c instead of
-	  plain abort() to allow debuggers trapping and overriding them
-	- added verbosity of gscanner.c to catch deprecated code paths
-	- added verbosity of gutils.c to catch deprecated code paths
-	- object ref/unref traps (consult debugging.txt) and object bookkeeping
-	  in gobject.c
-	- extra validity checks in gsignal.c

gobject/gtype.c

@@ -87,6 +87,20 @@
  * be at least three characters long. There is no upper length limit. The first
  * character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent
  * characters can be letters, numbers or any of ‘-_+’.
+ *
+ * # Runtime Debugging
+ *
+ * When `G_ENABLE_DEBUG` is defined during compilation, the GObject library
+ * supports an environment variable `GOBJECT_DEBUG` that can be set to a
+ * combination of flags to trigger debugging messages about
+ * object bookkeeping and signal emissions during runtime.
+ *
+ * The currently supported flags are:
+ *  - `objects`: Tracks all #GObject instances in a global hash table called
+ *    `debug_objects_ht`, and prints the still-alive objects on exit.
+ *  - `instance-count`: Tracks the number of instances of every #GType and makes
+ *    it available via the g_type_get_instance_count() function.
+ *  - `signals`: Currently unused.
  */
 
 
@@ -3953,8 +3967,8 @@ g_type_query (GType       type,
  *
  * Returns the number of instances allocated of the particular type;
  * this is only available if GLib is built with debugging support and
- * the instance_count debug flag is set (by setting the GOBJECT_DEBUG
- * variable to include instance-count).
+ * the `instance-count` debug flag is set (by setting the `GOBJECT_DEBUG`
+ * variable to include `instance-count`).
  *
  * Returns: the number of instances allocated of the given type;
  *   if instance counts are not available, returns 0.
@@ -4468,7 +4482,7 @@ _g_type_boxed_init (GType          type,
  * flags.  Since GLib 2.36, the type system is initialised automatically
  * and this function does nothing.
  *
- * If you need to enable debugging features, use the GOBJECT_DEBUG
+ * If you need to enable debugging features, use the `GOBJECT_DEBUG`
  * environment variable.
  *
  * Deprecated: 2.36: the type system is now initialised automatically

gobject/gtype.h

@@ -714,7 +714,7 @@ struct _GTypeQuery
  * These flags used to be passed to g_type_init_with_debug_flags() which
  * is now deprecated.
  *
- * If you need to enable debugging features, use the GOBJECT_DEBUG
+ * If you need to enable debugging features, use the `GOBJECT_DEBUG`
  * environment variable.
  *
  * Deprecated: 2.36: g_type_init() is now done automatically