Clarify stratigraphic column and rank interpretation docs

Improved and expanded documentation for StratigraphicColumn and StratigraphicColumnRankInterpretation classes across RESQML 2.0.1 and 2.2, clarifying ordering criteria, rank detail, and push-back requirements. Updated parameter names for clarity and consistency, and enhanced SWIG interface comments to match. No functional code changes were made.

Author: philippeVerney

src/common/DataObjectRepository.h

@@ -1702,8 +1702,7 @@ namespace COMMON_NS
 		DLL_IMPORT_OR_EXPORT RESQML2_NS::StratigraphicColumn* createStratigraphicColumn(const std::string & guid, const std::string & title);
 
 		/**
-		 * @brief	Creates a stratigraphic column rank interpretation ordered by age into this
-		 * 			repository.
+		 * @brief	Creates a stratigraphic column rank interpretation ordered by ascending age into this repository.
 		 *
 		 * @exception	std::invalid_argument	If the default RESQML version is unrecognized.
 		 * @exception	std::invalid_argument	If <tt>orgFeat == nullptr</tt> or if in a RESQML v2.0
@@ -1721,8 +1720,7 @@ namespace COMMON_NS
 		DLL_IMPORT_OR_EXPORT RESQML2_NS::StratigraphicColumnRankInterpretation* createStratigraphicColumnRankInterpretationInAge(RESQML2_NS::Model * orgFeat, const std::string & guid, const std::string & title, uint64_t rank);
 
 		/**
-		 * @brief	Creates a stratigraphic column rank interpretation ordered by apparent depth into
-		 * 			this repository
+		 * @brief	Creates a stratigraphic column rank interpretation ordered by ascending apparent depth into this repository
 		 *
 		 * @exception	std::invalid_argument	If the default RESQML version is unrecognized.
 		 * @exception	std::invalid_argument	If <tt>orgFeat == nullptr</tt> or if in a RESQML v2.0

src/resqml2/StratigraphicColumn.h

@@ -25,12 +25,9 @@ namespace RESQML2_NS
 	class StratigraphicColumnRankInterpretation;
 
 	/**
-	 * @brief	A global interpretation of the stratigraphy, which can be made up of several ranks of
-	 * 			stratigraphic unit interpretations.
-	 * 			
-	 * 			BUSINESS RULE: All stratigraphic column rank interpretations that make up a
-	 * 			stratigraphic column must be ordered by age.
-	 */
+	* @brief	A global interpretation of the stratigraphy, which can be made up of several ranks of
+	* 			stratigraphic unit interpretations.
+	*/
 	class StratigraphicColumn : public COMMON_NS::AbstractObject
 	{
 	public:
@@ -39,6 +36,8 @@ namespace RESQML2_NS
 		virtual ~StratigraphicColumn() = default;
 
 		/**
+		 * Stratigraphic column ranks must be pushed back from the coarsest rank to the most detailed one.
+		 *		
 		 * Pushes a back a stratigraphic column rank interpretation into this stratigraphic column.
 		 *
 		 * @exception	std::invalid_argument	If <tt>stratiColumnRank == nullptr</tt>

src/resqml2/StratigraphicColumnRankInterpretation.h

@@ -31,10 +31,10 @@ namespace RESQML2_NS
 {
 	class StratigraphicUnitInterpretation;
 
-	/**
-	 * @brief	A stratigraphic column rank interpretation is a global hierarchy containing an
-	 * 			ordered list of stratigraphic unit interpretations.
-	 */
+	/** 
+	* @brief	A stratigraphic column rank interpretation contains an ordered list of stratigraphic unit interpretations.
+	*			It corresponds to a level of detail of the stratigraphic column. First indexed ranks are coarser than last indexed ranks which are more detailed.
+	*/
 	class StratigraphicColumnRankInterpretation : public AbstractStratigraphicOrganizationInterpretation
 	{
 	public:
@@ -43,9 +43,13 @@ namespace RESQML2_NS
 		virtual ~StratigraphicColumnRankInterpretation() = default;
 
 		/**
-		 * Adds a stratigraphic unit interpretation to this stratigraphic column rank interpretation.
-		 * Does add the inverse relationship i.e. from the included stratigraphic unit interpretation to
-		 * this stratigraphic column rank interpretation.
+		 * Pushes back a stratigraphic unit interpretation to this stratigraphic column rank interpretation.
+		 * The stratigraphic unit interpretation must be pushed back according to the ordering criteria of the stratigraphic column rank interpretation:
+		 *  - If the (ascending) ordering criteria is age then units must be pushed back from the youngest to oldest.
+		 *	- If the (ascending) ordering criteria is apparent depth then units must be pushed back from the shallowest one to the deepest one.
+		 *	- If the (ascending) ordering criteria is measured depth then units must be pushed back
+		 *		from the first drilled trajectory stations to the latest drilled trajectory stations of the wellbore.
+		 * Remark : RESQML2.0.1 does not explicitely states that the ordering criteria is ascending but RESQML 2.2 does.
 		 *
 		 * @exception	std::invalid_argument	If @p stratiUnitInterpretation is @c nullptr.
 		 *

src/resqml2_0_1/StratigraphicColumn.h

@@ -22,7 +22,10 @@ under the License.
 
 namespace RESQML2_0_1_NS
 {
-	/** This class is a container for other organizations that are consistent to each others. */
+	/**
+	* @brief	A global interpretation of the stratigraphy, which can be made up of several ranks of
+	* 			stratigraphic unit interpretations.
+	*/
 	class StratigraphicColumn final : public RESQML2_NS::StratigraphicColumn
 	{
 	public:
@@ -56,6 +59,15 @@ namespace RESQML2_0_1_NS
 		/** Destructor does nothing since the memory is managed by the gsoap context. */
 		~StratigraphicColumn() = default;
 
+		/**
+		 * Stratigraphic column ranks must be pushed back from the coarsest rank to the most detailed one.
+		 *
+		 * Pushes a back a stratigraphic column rank interpretation into this stratigraphic column.
+		 *
+		 * @exception	std::invalid_argument	If <tt>stratiColumnRank == nullptr</tt>
+		 *
+		 * @param [in]	stratiColumnRank	A stratigraphic column rank interpretation.
+		 */
 		DLL_IMPORT_OR_EXPORT void pushBackStratiColumnRank(RESQML2_NS::StratigraphicColumnRankInterpretation * stratiColumnRank) final;
 
 		DLL_IMPORT_OR_EXPORT unsigned int getStratigraphicColumnRankInterpretationCount() const final;

src/resqml2_0_1/StratigraphicColumnRankInterpretation.cpp

@@ -30,7 +30,8 @@ using namespace gsoap_resqml2_0_1;
 
 const char* StratigraphicColumnRankInterpretation::XML_NS = "resqml20";
 
-StratigraphicColumnRankInterpretation::StratigraphicColumnRankInterpretation(RESQML2_NS::Model * orgFeat, const std::string & guid, const std::string & title, uint64_t rank, gsoap_resqml2_0_1::resqml20__OrderingCriteria orderingCriteria)
+StratigraphicColumnRankInterpretation::StratigraphicColumnRankInterpretation(RESQML2_NS::Model * orgFeat, const std::string & guid, const std::string & title,
+	uint64_t rank, gsoap_resqml2_0_1::resqml20__OrderingCriteria ascendingOrderingCriteria)
 {
 	if (orgFeat == nullptr) {
 		throw invalid_argument("The interpreted organization feature cannot be null.");
@@ -43,10 +44,10 @@ StratigraphicColumnRankInterpretation::StratigraphicColumnRankInterpretation(RES
 	gsoapProxy2_0_1 = soap_new_resqml20__obj_USCOREStratigraphicColumnRankInterpretation(orgFeat->getGsoapContext());
 	static_cast<_resqml20__StratigraphicColumnRankInterpretation*>(gsoapProxy2_0_1)->Domain = resqml20__Domain::mixed;
 	static_cast<_resqml20__StratigraphicColumnRankInterpretation*>(gsoapProxy2_0_1)->Index = rank;
-	static_cast<_resqml20__StratigraphicColumnRankInterpretation*>(gsoapProxy2_0_1)->OrderingCriteria = orderingCriteria;
+	static_cast<_resqml20__StratigraphicColumnRankInterpretation*>(gsoapProxy2_0_1)->OrderingCriteria = ascendingOrderingCriteria;
 
 	initMandatoryMetadata();
-	setMetadata(guid, title, std::string(), -1, std::string(), std::string(), -1, std::string());
+	setMetadata(guid, title, "", -1, "", "", -1, "");
 
 	orgFeat->getRepository()->addDataObject(unique_ptr<COMMON_NS::AbstractObject>{this});
 	setInterpretedFeature(orgFeat);

src/resqml2_0_1/StratigraphicColumnRankInterpretation.h

@@ -23,7 +23,8 @@ under the License.
 namespace RESQML2_0_1_NS
 {
 	/**
-	* This class is a container for other organizations that are consistent to each others.
+	* A rank of a stratigraphic column corresponds to a level of detail of the stratigraphic column.
+	* First indexed ranks are coarser than last indexed ranks.
 	*/
 	class StratigraphicColumnRankInterpretation final : public RESQML2_NS::StratigraphicColumnRankInterpretation
 	{
@@ -49,7 +50,8 @@ namespace RESQML2_0_1_NS
 		 * 									column.
 		 * @param 	  	orderingCriteria	How the included horizons are ordered.
 		 */
-		StratigraphicColumnRankInterpretation(RESQML2_NS::Model * orgFeat, const std::string & guid, const std::string & title, uint64_t rank, gsoap_resqml2_0_1::resqml20__OrderingCriteria orderingCriteria);
+		StratigraphicColumnRankInterpretation(RESQML2_NS::Model * orgFeat, const std::string & guid, const std::string & title,
+			uint64_t rank, gsoap_resqml2_0_1::resqml20__OrderingCriteria ascendingOrderingCriteria);
 
 		/**
 		* Creates an instance of this class by wrapping a gsoap instance.
@@ -60,6 +62,19 @@ namespace RESQML2_0_1_NS
 		/** Destructor does nothing since the memory is managed by the gsoap context. */
 		~StratigraphicColumnRankInterpretation() = default;
 
+		/**
+		 * Pushes back a stratigraphic unit interpretation to this stratigraphic column rank interpretation.
+		 * The stratigraphic unit interpretation must be pushed back according to the ordering criteria of the stratigraphic column rank interpretation:
+		 *  - If the (ascending) ordering criteria is age then units must be pushed back from the youngest to oldest.
+		 *	- If the (ascending) ordering criteria is apparent depth then units must be pushed back from the shallowest one to the deepest one.
+		 *	- If the (ascending) ordering criteria is measured depth then units must be pushed back
+		 *		from the first drilled trajectory stations to the latest drilled trajectory stations of the wellbore.
+		 * Remark : RESQML2.0.1 does not explicitely states that the ordering criteria is ascending but RESQML 2.2 does.
+		 *
+		 * @exception	std::invalid_argument	If @p stratiUnitInterpretation is @c nullptr.
+		 *
+		 * @param [in]	stratiUnitInterpretation	The stratigraphic unit interpretation to add.
+		 */
 		DLL_IMPORT_OR_EXPORT void pushBackStratiUnitInterpretation(RESQML2_NS::StratigraphicUnitInterpretation * stratiUnitInterpretation) final;
 
 		DLL_IMPORT_OR_EXPORT void setHorizonOfLastContact(RESQML2_NS::HorizonInterpretation * partOf) final;

src/resqml2_2/StratigraphicColumn.h

@@ -22,7 +22,10 @@ under the License.
 
 namespace RESQML2_2_NS
 {
-	/** This class is a container for other organizations that are consistent to each others. */
+	/**
+	* @brief	A global interpretation of the stratigraphy, which can be made up of several ranks of
+	* 			stratigraphic unit interpretations.
+	*/
 	class StratigraphicColumn final : public RESQML2_NS::StratigraphicColumn
 	{
 	public:
@@ -56,6 +59,9 @@ namespace RESQML2_2_NS
 		/** Destructor does nothing since the memory is managed by the gsoap context. */
 		~StratigraphicColumn() = default;
 
+		/**
+		* Stratigraphic column ranks must be pushed back from the coarsest rank to the most detailed one.
+		*/
 		DLL_IMPORT_OR_EXPORT void pushBackStratiColumnRank(RESQML2_NS::StratigraphicColumnRankInterpretation * stratiColumnRank) final;
 
 		DLL_IMPORT_OR_EXPORT unsigned int getStratigraphicColumnRankInterpretationCount() const final;

src/resqml2_2/StratigraphicColumnRankInterpretation.cpp

@@ -26,18 +26,19 @@ using namespace std;
 using namespace RESQML2_2_NS;
 using namespace gsoap_eml2_3;
 
-StratigraphicColumnRankInterpretation::StratigraphicColumnRankInterpretation(RESQML2_NS::Model * orgFeat, const std::string & guid, const std::string & title, uint64_t rank, gsoap_resqml2_0_1::resqml20__OrderingCriteria orderingCriteria)
+StratigraphicColumnRankInterpretation::StratigraphicColumnRankInterpretation(RESQML2_NS::Model * orgFeat, const std::string & guid, const std::string & title,
+	uint64_t rank, gsoap_resqml2_0_1::resqml20__OrderingCriteria ascendingOrderingCriteria)
 {
 	if (orgFeat == nullptr) {
 		throw invalid_argument("The interpreted organization feature cannot be null.");
 	}
 
 	gsoapProxy2_3 = soap_new_resqml22__StratigraphicColumnRankInterpretation(orgFeat->getGsoapContext());
 	static_cast<_resqml22__StratigraphicColumnRankInterpretation*>(gsoapProxy2_3)->RankInStratigraphicColumn = rank;
-	static_cast<_resqml22__StratigraphicColumnRankInterpretation*>(gsoapProxy2_3)->AscendingOrderingCriteria = static_cast<resqml22__OrderingCriteria>(orderingCriteria);
+	static_cast<_resqml22__StratigraphicColumnRankInterpretation*>(gsoapProxy2_3)->AscendingOrderingCriteria = static_cast<resqml22__OrderingCriteria>(ascendingOrderingCriteria);
 
 	initMandatoryMetadata();
-	setMetadata(guid, title, std::string(), -1, std::string(), std::string(), -1, std::string());
+	setMetadata(guid, title, "", -1, "", "", -1, "");
 
 	orgFeat->getRepository()->addDataObject(unique_ptr<COMMON_NS::AbstractObject>{this});
 	setInterpretedFeature(orgFeat);

src/resqml2_2/StratigraphicColumnRankInterpretation.h

@@ -23,7 +23,8 @@ under the License.
 namespace RESQML2_2_NS
 {
 	/**
-	* This class is a container for other organizations that are consistent to each others.
+	* @brief	A stratigraphic column rank interpretation contains an ordered list of stratigraphic unit interpretations.
+	*			It corresponds to a level of detail of the stratigraphic column. First indexed ranks are coarser than last indexed ranks which are more detailed.
 	*/
 	class StratigraphicColumnRankInterpretation final : public RESQML2_NS::StratigraphicColumnRankInterpretation
 	{
@@ -48,7 +49,8 @@ namespace RESQML2_2_NS
 		 * 									column.
 		 * @param 	  	orderingCriteria	How the included horizons are ordered.
 		 */
-		StratigraphicColumnRankInterpretation(RESQML2_NS::Model * orgFeat, const std::string & guid, const std::string & title, uint64_t rank, gsoap_resqml2_0_1::resqml20__OrderingCriteria orderingCriteria);
+		StratigraphicColumnRankInterpretation(RESQML2_NS::Model * orgFeat, const std::string & guid, const std::string & title,
+			uint64_t rank, gsoap_resqml2_0_1::resqml20__OrderingCriteria ascendingOrderingCriteria);
 
 		/**
 		* Creates an instance of this class by wrapping a gsoap instance.
@@ -59,6 +61,19 @@ namespace RESQML2_2_NS
 		/** Destructor does nothing since the memory is managed by the gsoap context. */
 		~StratigraphicColumnRankInterpretation() = default;
 
+		/**
+		 * Pushes back a stratigraphic unit interpretation to this stratigraphic column rank interpretation.
+		 * The stratigraphic unit interpretation must be pushed back according to the ordering criteria of the stratigraphic column rank interpretation:
+		 *  - If the (ascending) ordering criteria is age then units must be pushed back from the youngest to oldest.
+		 *	- If the (ascending) ordering criteria is apparent depth then units must be pushed back from the shallowest one to the deepest one.
+		 *	- If the (ascending) ordering criteria is measured depth then units must be pushed back
+		 *		from the first drilled trajectory stations to the latest drilled trajectory stations of the wellbore.
+		 * Remark : RESQML2.0.1 does not explicitely states that the ordering criteria is ascending but RESQML 2.2 does.
+		 *
+		 * @exception	std::invalid_argument	If @p stratiUnitInterpretation is @c nullptr.
+		 *
+		 * @param [in]	stratiUnitInterpretation	The stratigraphic unit interpretation to add.
+		 */
 		DLL_IMPORT_OR_EXPORT void pushBackStratiUnitInterpretation(RESQML2_NS::StratigraphicUnitInterpretation * stratiUnitInterpretation) final;
 
 		DLL_IMPORT_OR_EXPORT void setHorizonOfLastContact(RESQML2_NS::HorizonInterpretation * partOf) final;

swig/swigModule.i

@@ -2088,8 +2088,7 @@ import com.f2i_consulting.fesapi.*;
 		RESQML2_NS::StratigraphicColumn* createStratigraphicColumn(const std::string & guid, const std::string & title);
 
 		/**
-		 * @brief	Creates a stratigraphic column rank interpretation ordered by age into this
-		 * 			repository.
+		 * @brief	Creates a stratigraphic column rank interpretation ordered by ascending age into this repository.
 		 *
 		 * @exception	std::invalid_argument	If the default RESQML version is unrecognized.
 		 * @exception	std::invalid_argument	If <tt>orgFeat == nullptr</tt> or if in a RESQML v2.0
@@ -2107,8 +2106,7 @@ import com.f2i_consulting.fesapi.*;
 		RESQML2_NS::StratigraphicColumnRankInterpretation* createStratigraphicColumnRankInterpretationInAge(RESQML2_NS::Model * orgFeat, const std::string & guid, const std::string & title, uint64_t rank);
 
 		/**
-		 * @brief	Creates a stratigraphic column rank interpretation ordered by apparent depth into
-		 * 			this repository
+		 * @brief	Creates a stratigraphic column rank interpretation ordered by ascending apparent depth into this repository
 		 *
 		 * @exception	std::invalid_argument	If the default RESQML version is unrecognized.
 		 * @exception	std::invalid_argument	If <tt>orgFeat == nullptr</tt> or if in a RESQML v2.0