From b073e4385c93828d3811aea930136b11769d85cf Mon Sep 17 00:00:00 2001
From: Pierre Goiffon <pierre.goiffon@combodo.com>
Date: Thu, 6 Jan 2022 14:49:34 +0100
Subject: [PATCH] :bulb: Document versions constants (#255)

Clarify ITOP_VERSION and ITOP_DESIGN_LATEST_VERSION uses
---
 core/config.class.inc.php            | 12 +++++++++++-
 setup/itopdesignformat.class.inc.php | 21 ++++++++++++++-------
 2 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/core/config.class.inc.php b/core/config.class.inc.php
index c887a7a76..243ff1c1d 100644
--- a/core/config.class.inc.php
+++ b/core/config.class.inc.php
@@ -22,7 +22,17 @@
 
 define('ITOP_APPLICATION', 'iTop');
 define('ITOP_APPLICATION_SHORT', 'iTop');
-define('ITOP_VERSION', '2.7.0-dev'); // @see utils::GetItopVersionShort() and utils::GetItopVersionWikiSyntax()
+
+/**
+ * Constant containing the application version
+ * Warning: this might be different from iTop core version!
+ *
+ * @see     ITOP_DESIGN_LATEST_VERSION for iTop core version
+ *
+ * @used-by utils::GetItopPatchVersion
+ */
+define('ITOP_VERSION', '2.7.0-dev');
+
 define('ITOP_REVISION', 'svn');
 define('ITOP_BUILD_DATE', '$WCNOW$');
 define('ITOP_VERSION_FULL', ITOP_VERSION.'-'.ITOP_REVISION);
diff --git a/setup/itopdesignformat.class.inc.php b/setup/itopdesignformat.class.inc.php
index 87c12ff6d..f588c8dd4 100644
--- a/setup/itopdesignformat.class.inc.php
+++ b/setup/itopdesignformat.class.inc.php
@@ -17,7 +17,14 @@
  * You should have received a copy of the GNU Affero General Public License
  */
 
-define('ITOP_DESIGN_LATEST_VERSION', '1.7'); // iTop >= 2.7.0
+
+/**
+ * iTop Datamodel XML format version
+ * And also iTop core version
+ *
+ * To test for iTop core version use this constant instead of {@link ITOP_VERSION} !
+ */
+define('ITOP_DESIGN_LATEST_VERSION', '1.7');
 
 /**
  * Utility to upgrade the format of a given XML datamodel to the latest version
@@ -26,7 +33,7 @@ define('ITOP_DESIGN_LATEST_VERSION', '1.7'); // iTop >= 2.7.0
  * To test migration methods check {@link \Combodo\iTop\Test\UnitTest\Setup\TestForITopDesignFormatClass}
  *
  * Usage:
- * 
+ *
  * $oDocument = new DOMDocument();
  * $oDocument->load($sXMLFile);
  * $oFormat = new iTopDesignFormat($oDocument);
@@ -60,31 +67,31 @@ class iTopDesignFormat
 			'next' => '1.3',
 			'go_to_next' => 'From12To13',
 		),
-		'1.3' => array(
+		'1.3' => array( // iTop >= 2.2.0
 			'previous' => '1.2',
 			'go_to_previous' => 'From13To12',
 			'next' => '1.4',
 			'go_to_next' => 'From13To14',
 		),
-		'1.4' => array(
+		'1.4' => array( // iTop >= 2.4.0
 			'previous' => '1.3',
 			'go_to_previous' => 'From14To13',
 			'next' => '1.5',
 			'go_to_next' => 'From14To15',
 		),
-		'1.5' => array(
+		'1.5' => array( // iTop >= 2.5.0
 			'previous' => '1.4',
 			'go_to_previous' => 'From15To14',
 			'next' => '1.6',
 			'go_to_next' => 'From15To16',
 		),
-		'1.6' => array(
+		'1.6' => array( // iTop >= 2.6.0
 			'previous' => '1.5',
 			'go_to_previous' => 'From16To15',
 			'next' => '1.7',
 			'go_to_next' => 'From16To17',
 		),
-		'1.7' => array(
+		'1.7' => array( // iTop >= 2.7.0
 			'previous' => '1.6',
 			'go_to_previous' => 'From17To16',
 			'next' => null,