From 99dd95806d6e29dca3b7dc639a8bd5193417c3a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?=
 <shyouhei@ruby-lang.org>
Date: Tue, 8 Jun 2021 11:25:50 +0900
Subject: include/ruby/version.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/version.h | 106 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 102 insertions(+), 4 deletions(-)

(limited to 'include')

diff --git a/include/ruby/version.h b/include/ruby/version.h
index d25008fad9..104f78a0c6 100644
--- a/include/ruby/version.h
+++ b/include/ruby/version.h
@@ -20,40 +20,138 @@
  * check the features with mkmf.rb instead.
  */
 
-/* The origin. */
+/**
+ * @name The origin.
+ *
+ * These information never change.  Just written here to remember.
+ *
+ * @{
+ */
+
+/** Author of this project. */
 #define RUBY_AUTHOR "Yukihiro Matsumoto"
+
+/** Ruby's birth year. */
 #define RUBY_BIRTH_YEAR 1993
+
+/** Ruby's birth month. */
 #define RUBY_BIRTH_MONTH 2
+
+/** Ruby's birth day. */
 #define RUBY_BIRTH_DAY 24
 
-/* API version */
+/** @} */
+
+/**
+ * @name The API version.
+ *
+ * API version  is different from  binary version.   These numbers are  for API
+ * stability.  When you  have distinct API versions x and  y, you cannot expect
+ * codes targeted to x also works for y.
+ *
+ * However   let   us  repeat   here   that   it's   a   BAD  idea   to   check
+ * #RUBY_API_VERSION_CODE form extension libraries.  Different API versions are
+ * just different.  There is no such thing like upper compatibility.
+ *
+ * @{
+ */
+
+/**
+ * Major version.  This  digit changes sometimes for various  reasons, but that
+ * doesn't mean a total rewrite.  Practically  when it comes to API versioning,
+ * major and minor version changes are equally catastrophic.
+ */
 #define RUBY_API_VERSION_MAJOR 3
+
+/**
+ * Minor  version.   As of  writing  this  version changes  annually.   Greater
+ * version doesn't mean "better"; they just mean years passed.
+ */
 #define RUBY_API_VERSION_MINOR 1
+
+/**
+ * Teeny version.  This digit  is kind of reserved these days.   Kept 0 for the
+ * entire 2.x era.  Waiting for future uses.
+ */
 #define RUBY_API_VERSION_TEENY 0
+
+/**
+ * This macro is API versions encoded into a C integer.
+ *
+ * @note  Use mkmf.
+ * @note  Don't rely on it.
+ */
 #define RUBY_API_VERSION_CODE (RUBY_API_VERSION_MAJOR*10000+RUBY_API_VERSION_MINOR*100+RUBY_API_VERSION_TEENY)
 
+/** @} */
+
 #ifdef RUBY_EXTERN
 /* Internal note: this file could be included from verconf.mk _before_
  * generating config.h, on Windows.  The #ifdef above is to trick such
  * situation. */
 RBIMPL_SYMBOL_EXPORT_BEGIN()
 
-/*
- * Interfaces from extension libraries.
+/**
+ * @name Interfaces from extension libraries.
  *
  * Before using these infos, think thrice whether they are really
  * necessary or not, and if the answer was yes, think twice a week
  * later again.
+ *
+ * @{
  */
+
+/** API versions, in { major, minor, teeny } order.  */
 RUBY_EXTERN const int ruby_api_version[3];
+
+/**
+ * Stringised version.
+ *
+ * @note  This is  the runtime version, not  the API version.  For  instance it
+ *        was `"2.5.9"` when ::ruby_api_version was `{ 2, 5, 0 }`.
+ */
 RUBY_EXTERN const char ruby_version[];
+
+/** Date of release, in a C string. */
 RUBY_EXTERN const char ruby_release_date[];
+
+/**
+ * Target platform identifier, in a C string.
+ *
+ * @note  Seasoned  UNIX   programmers  should   beware  that   this  "platform
+ *        identifier"  is  our invention;  not  always  identical to  so-called
+ *        target triplets  that GNU systems  use.  For instance  on @shyouhei's
+ *        machine, ::ruby_platform is `"x64_64-linux"` while its target triplet
+ *        is `x86_64-pc-linux-gnu`.
+ * @note  Note also that we support Windows.
+ */
 RUBY_EXTERN const char ruby_platform[];
+
+/**
+ * This  is a  monotonic  increasing integer  that  describes specific  "patch"
+ * level.  You can know the exact changeset your binary is running by this info
+ * (and ::ruby_version), unless  this is -1.  -1 means there  is no release yet
+ * for the version; ruby is actively developed. 0 means the initial GA version.
+ */
 RUBY_EXTERN const int  ruby_patchlevel;
+
+/**
+ * This is what `ruby -v` prints to the standard error.  Something like:
+ * `"ruby 2.5.9p229 (2021-04-05 revision 67829) [x86_64-linux]"`
+ */
 RUBY_EXTERN const char ruby_description[];
+
+/** Copyright notice. */
 RUBY_EXTERN const char ruby_copyright[];
+
+/**
+ * This  is just  `"ruby"`  for  us.  But  different  implementations can  have
+ * different strings here.
+ */
 RUBY_EXTERN const char ruby_engine[];
 
+/** @} */
+
 RBIMPL_SYMBOL_EXPORT_END()
 #endif
 
-- 
cgit v1.2.3