0026936: Drawbacks of inlining in new type system in OCCT 7.0 -- manual

Restored possibility to have out-of-line implementation of DynamicCast() and STANDART_TYPE():
- Macro STANDARD_TYPE() now resolves to function get_type_descriptor() of the class
- Macro DEFINE_STANDARD_RTTI is replaced by two variants:
  - DEFINE_STANDARD_RTTI_INLINE works as before, defining DynamicCast() and get_type_descriptor() as inline functions
  - DEFINE_STANDARD_RTTIEXT declares DynamicCast() and get_type_descriptor() as exported
- Macro IMPLEMENT_STANDARD_RTTIEXT provides definition of DynamicCast() and get_type_descriptor() for a class

Upgrade script amended to replace DEFINE_STANDARD_RTTI by pair of DEFINE_STANDARD_RTTIEXT / IMPLEMENT_STANDARD_RTTIEXT if source file with the same name as header is found in the same folder, and by DEFINE_STANDARD_RTTI_INLINE if either source is not found or class is defined in the source (i.e. not in header)

Upgrade tool improved to recognize include statements with path prefix, like #include <occt/gp_Pnt.hxx>
Code corrected to eliminate warnings reported by upgrade tool.
Template of CXX file for testing upgrade tool added.

Documentation of upgrade procedure updated.

dox/dev_guides/upgrade/upgrade.md

@@ -86,7 +86,7 @@ Alternative solution is to use legacy generator of project files (extracted from
 
 @subsubsection upgrade_occt700_cdl_auto Automatic upgrade
 
-Most of typical changes required for upgrading code to use OCCT 7.0 can be done automatically using the *upgrade* tool included in OCCT 7.0.
+Most of typical changes required for upgrading code for OCCT 7.0 can be done automatically using the *upgrade* tool included in OCCT 7.0.
 This tool is a Tcl script, thus Tcl should be available on your workstation to run it.
 
 Example:
@@ -106,11 +106,16 @@ Run upgrade tool without arguments to see the list of available options.
 
 Upgrade tool performs the following changes in the code.
 
-1. Adds second argument to macro DEFINE_STANDARD_RTTI indicating base class for its argument class (if inheritance is recognized by the script):
+1. Replaces macro DEFINE_STANDARD_RTTI by DEFINE_STANDARD_RTTIEXT, with second argument indicating base class for the main argument class (if inheritance is recognized by the script):
 ~~~~~
-DEFINE_STANDARD_RTTI(Class) -> DEFINE_STANDARD_RTTI(Class, Base)
+DEFINE_STANDARD_RTTI(Class) -> DEFINE_STANDARD_RTTIEXT(Class, Base)
 ~~~~~
 
+   @note If macro DEFINE_STANDARD_RTTI with two arguments (used in intermediate development versions of OCCT 7.0) is found, the script will convert it to either DEFINE_STANDARD_RTTIEXT or DEFINE_STANDARD_RTTI_INLINE. 
+   The former case is used if current file is header and source file with the same name is found in the same folder. 
+   In this case, macro IMPLEMENT_STANDARD_RTTI is injected in the corresponding source file.
+   The latter variant defines all methods for RTTI as inline, and does not require IMPLEMENT_STANDARD_RTTIEXT macro. 
+
 2. Replaces forward declarations of collection classes previously generated from CDL generics (defined in TCollection package) by \#include of corresponding header:
 ~~~~~
 class TColStd_Array1OfReal; -> #include <TColStd_Array1OfReal.hxx>
@@ -159,9 +164,11 @@ Namespace::Handle(Class) -> Handle(Namespace::Class)
 
 10. Adds \#include for all classes used as argument to macro STANDARD_TYPE(), except of already included ones;
 
-11. Removes uses of obsolete macros IMPLEMENT_DOWNCAST() and IMPLEMENT_STANDARD_*().
+11. Removes uses of obsolete macros IMPLEMENT_DOWNCAST and IMPLEMENT_STANDARD_*, except IMPLEMENT_STANDARD_RTTIEXT.
 
-  > If you plan to keep compatibility of your code with older versions of OCCT, add option "-compat" to avoid the latter change. See also @ref upgrade_occt700_cdl_compat.
+    @note If you plan to keep compatibility of your code with older versions of OCCT, add option "-compat" to avoid the latter change. See also @ref upgrade_occt700_cdl_compat.
+
+.
 
 As long as the upgrade routine runs, some information messages are sent to the standard output. 
 In some cases the warnings or errors like the following may appear:
@@ -171,7 +178,7 @@ In some cases the warnings or errors like the following may appear:
 ~~~~~
 
 Be sure to check carefully all reported errors and warnings, as corresponding places likely will require manual corrections.
-In some cases these messages may help you to detect errors in your code, for instance, cases where DEFINE_STANDARD_RTTI macro passes invalid class name as an argument.
+In some cases these messages may help you to detect errors in your code, for instance, cases where DEFINE_STANDARD_RTTI macro is used with incorrect class name as an argument.
 
 @subsubsection upgrade_occt700_cdl_compiler Possible compiler errors
 
@@ -323,16 +330,17 @@ aBC->Transform (T); // access violation in OCCT 7.0
 
 If you like to preserve compatibility of your application code with OCCT versions 6.x even after upgrade to 7.0, consider the following suggestions:
 
-1. When running automatic upgrade tool, add option *-compat*.
+1. If your code used sequences of macros IMPLEMENT_STANDARD_... generated by WOK, replace them by single macro IMPLEMENT_STANDARD_RTTIEXT
 
-2. In order to overcome incompatibility of macro DEFINE_STANDARD_RTTI which has additional argument in OCCT 7.0, you can replace (after upgrade) its use in your code by your own version-dependent macro, which resolves to either 6.x or 7.x version.
+2. When running automatic upgrade tool, add option *-compat*.
+
+3. Define macros DEFINE_STANDARD_RTTIEXT and DEFINE_STANDARD_RTTI_INLINE when building with previous versions of OCCT, resolving to DEFINE_STANDARD_RTTI with single argument 
 
    Example:
 ~~~~~   
 #if OCC_VERSION_HEX < 0x070000
-  #define DEFINE_STANDARD_RTTI_COMPAT(C1,C2) DEFINE_STANDARD_RTTI(C1) 
-#else
-  #define DEFINE_STANDARD_RTTI_COMPAT(C1,C2) DEFINE_STANDARD_RTTI(C1,C2) 
+  #define DEFINE_STANDARD_RTTIEXT(C1,C2) DEFINE_STANDARD_RTTI(C1)
+  #define DEFINE_STANDARD_RTTI_INLINE(C1,C2) DEFINE_STANDARD_RTTI(C1)
 #endif
 ~~~~~