Update the documentation of the versioning macros

2 files changed, 34 insertions, 13 deletions

diff --git a/json-glib/json-version-macros.h b/json-glib/json-version-macros.h
index c1c269c..75ac770 100644
--- a/json-glib/json-version-macros.h
+++ b/json-glib/json-version-macros.h
@@ -41,12 +41,32 @@
 #endif
 
 /* XXX: Each new cycle should add a new version symbol here */
+/**
+ * JSON_VERSION_1_0:
+ *
+ * The encoded representation of JSON-GLib version "1.0".
+ */
 #define JSON_VERSION_1_0        (G_ENCODE_VERSION (1, 0))
 
+/**
+ * JSON_VERSION_1_2:
+ *
+ * The encoded representation of JSON-GLib version "1.2".
+ */
 #define JSON_VERSION_1_2        (G_ENCODE_VERSION (1, 2))
 
+/**
+ * JSON_VERSION_1_4:
+ *
+ * The encoded representation of JSON-GLib version "1.4".
+ */
 #define JSON_VERSION_1_4        (G_ENCODE_VERSION (1, 4))
 
+/**
+ * JSON_VERSION_1_6:
+ *
+ * The encoded representation of JSON-GLib version "1.6".
+ */
 #define JSON_VERSION_1_6        (G_ENCODE_VERSION (1, 6))
 
 /* evaluates to the current stable version; for development cycles,
@@ -73,9 +93,10 @@
  * JSON_VERSION_MIN_REQUIRED:
  *
  * A macro that should be defined by the user prior to including
- * the gdk.h header.
- * The definition should be one of the predefined JSON version
- * macros: %JSON_VERSION_1_0, %JSON_VERSION_1_2,...
+ * the `json-glib/json-glib.h` header.
+ *
+ * The definition should be one of the predefined JSON-GLib version
+ * macros: `JSON_VERSION_1_0`, `JSON_VERSION_1_2`, ...
  *
  * This macro defines the lower bound for the JSON-GLib API to use.
  *
@@ -93,10 +114,10 @@
  * JSON_VERSION_MAX_ALLOWED:
  *
  * A macro that should be defined by the user prior to including
- * the json-glib.h header.
+ * the `json-glib/json-glib.h` header.
 
  * The definition should be one of the predefined JSON-GLib version
- * macros: %JSON_VERSION_1_0, %JSON_VERSION_1_2,...
+ * macros: `JSON_VERSION_1_0`, `JSON_VERSION_1_2`, ...
  *
  * This macro defines the upper bound for the JSON API-GLib to use.
  *
diff --git a/json-glib/json-version.h.in b/json-glib/json-version.h.in
index 8fe3a5b..3bd3490 100644
--- a/json-glib/json-version.h.in
+++ b/json-glib/json-version.h.in
@@ -31,35 +31,35 @@
 /**
  * JSON_MAJOR_VERSION:
  *
- * Json major version component (e.g. 1 if %JSON_VERSION is 1.2.3)
+ * Json major version component (e.g. 1 if `JSON_VERSION` is "1.2.3")
  */
 #define JSON_MAJOR_VERSION              (@JSON_MAJOR_VERSION@)
 
 /**
  * JSON_MINOR_VERSION:
  *
- * Json minor version component (e.g. 2 if %JSON_VERSION is 1.2.3)
+ * Json minor version component (e.g. 2 if `JSON_VERSION` is "1.2.3")
  */
 #define JSON_MINOR_VERSION              (@JSON_MINOR_VERSION@)
 
 /**
  * JSON_MICRO_VERSION:
  *
- * Json micro version component (e.g. 3 if %JSON_VERSION is 1.2.3)
+ * Json micro version component (e.g. 3 if `JSON_VERSION` is "1.2.3")
  */
 #define JSON_MICRO_VERSION              (@JSON_MICRO_VERSION@)
 
 /**
  * JSON_VERSION
  *
- * Json version.
+ * The version of JSON-GLib.
  */
 #define JSON_VERSION                    (@JSON_VERSION@)
 
 /**
  * JSON_VERSION_S:
  *
- * JSON-GLib version, encoded as a string, useful for printing and
+ * The version of JSON-GLib, encoded as a string, useful for printing and
  * concatenation.
  */
 #define JSON_VERSION_S                  "@JSON_VERSION@"
@@ -70,7 +70,7 @@
 /**
  * JSON_VERSION_HEX:
  *
- * JSON-GLib version, encoded as an hexadecimal number, useful for
+ * The version of JSON-GLib, encoded as an hexadecimal number, useful for
  * integer comparisons.
  */
 #define JSON_VERSION_HEX \
@@ -82,8 +82,8 @@
  * @minor: required minor version
  * @micro: required micro version
  *
- * Compile-time version checking. Evaluates to %TRUE if the version
- * of Json is greater than the required one.
+ * Compile-time version checking. Evaluates to `TRUE` if the version
+ * of JSON-GLib is greater than the required one.
  */
 #define JSON_CHECK_VERSION(major,minor,micro)   \
         (JSON_MAJOR_VERSION > (major) || \