From 229b76a388edd8d2eb9c3ec74dd32088a9083556 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Tue, 21 Nov 2023 17:16:12 +0000
Subject: [PATCH] docs: Move the version SECTION
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move it to a separate documentation file, since most of what’s covered
isn’t introspectable.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
---
 docs/reference/glib/glib.toml.in |  1 +
 docs/reference/glib/meson.build  |  1 +
 docs/reference/glib/version.md   | 46 ++++++++++++++++++++++++++++++++
 glib/gversion.c                  | 22 ---------------
 4 files changed, 48 insertions(+), 22 deletions(-)
 create mode 100644 docs/reference/glib/version.md

diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in
index 3c14921c2..acfdf49a1 100644
--- a/docs/reference/glib/glib.toml.in
+++ b/docs/reference/glib/glib.toml.in
@@ -71,6 +71,7 @@ content_files = [
   "data-structures.md",
   "uuid.md",
   "unicode.md",
+  "version.md",
 
   "threads-deprecated.md",
 ]
diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build
index 151a7794e..a0b03f18c 100644
--- a/docs/reference/glib/meson.build
+++ b/docs/reference/glib/meson.build
@@ -170,6 +170,7 @@ expand_content_files = [
   'data-structures.md',
   'unicode.md',
   'uuid.md',
+  'version.md',
 ]
 
 glib_toml = configure_file(input: 'glib.toml.in', output: 'glib.toml', configuration: toml_conf)
diff --git a/docs/reference/glib/version.md b/docs/reference/glib/version.md
new file mode 100644
index 000000000..4d9ddcfd7
--- /dev/null
+++ b/docs/reference/glib/version.md
@@ -0,0 +1,46 @@
+Title: Version Information
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2004 Matthias Clasen
+SPDX-FileCopyrightText: 2012 Emmanuele Bassi
+
+# Version Information
+
+GLib provides version information, primarily useful in configure
+checks for builds that have a configure script. Applications will
+not typically use the features described here.
+
+## Run-time Version Numbers
+
+The variables `glib_major_version`, `glib_minor_version`, `glib_micro_version`,
+`glib_binary_age` and `glib_interface_age` are all available to check.
+
+They can be compared using the function [func@GLib.check_version].
+
+## Compile-time Version Numbers
+
+ * [const@GLib.MAJOR_VERSION]
+ * [const@GLib.MINOR_VERSION]
+ * [const@GLib.MICRO_VERSION]
+ * [func@GLib.CHECK_VERSION]
+
+## Version Numbers
+
+The GLib headers annotate deprecated APIs in a way that produces
+compiler warnings if these deprecated APIs are used. The warnings
+can be turned off by defining the macro `GLIB_DISABLE_DEPRECATION_WARNINGS`
+before including the `glib.h` header.
+
+GLib also provides support for building applications against
+defined subsets of deprecated or new GLib APIs. Define the macro
+`GLIB_VERSION_MIN_REQUIRED` to specify up to what version of GLib
+you want to receive warnings about deprecated APIs. Define the
+macro `GLIB_VERSION_MAX_ALLOWED` to specify the newest version of
+GLib whose API you want to use.
+
+The macros `GLIB_VERSION_2_2`, `GLIB_VERSION_2_4`, …, `GLIB_VERSION_2_80`, etc.
+are defined automatically in each release, and can be used to set the value
+of macros like `GLIB_VERSION_MIN_REQUIRED`.
+
+The macros `GLIB_VERSION_CUR_STABLE` and `GLIB_VERSION_PREV_STABLE` are also
+automatically defined to point to the right version definitions.
+
diff --git a/glib/gversion.c b/glib/gversion.c
index b12929bbb..ade16fcde 100644
--- a/glib/gversion.c
+++ b/glib/gversion.c
@@ -28,28 +28,6 @@
 
 #include "gversion.h"
 
-/**
- * SECTION:version
- * @Title: Version Information
- * @Short_description: variables and functions to check the GLib version
- *
- * GLib provides version information, primarily useful in configure
- * checks for builds that have a configure script. Applications will
- * not typically use the features described here.
- *
- * The GLib headers annotate deprecated APIs in a way that produces
- * compiler warnings if these deprecated APIs are used. The warnings
- * can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS
- * before including the glib.h header.
- *
- * GLib also provides support for building applications against
- * defined subsets of deprecated or new GLib APIs. Define the macro
- * %GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib
- * you want to receive warnings about deprecated APIs. Define the
- * macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of
- * GLib whose API you want to use.
- */
-
 /**
  * glib_major_version:
  *