0027231: Obsolete OCCT features still mentioned in the documentation
authorabv <abv@opencascade.com>
Tue, 8 Mar 2016 11:12:45 +0000 (14:12 +0300)
committerabv <abv@opencascade.com>
Sat, 12 Mar 2016 06:18:11 +0000 (09:18 +0300)
A few remaining places mentioning .cdl files are corrected to mention only .hxx
Obsolete description of storage in old format is revised in OCAF User's Guide.

dox/dev_guides/contribution/coding_rules.md
dox/user_guides/boolean_operations/boolean_operations.md
dox/user_guides/draw_test_harness/draw_test_harness.md
dox/user_guides/foundation_classes/foundation_classes.md
dox/user_guides/ocaf/ocaf.md

index 999726f..c2cbed7 100644 (file)
@@ -81,7 +81,7 @@ Usually the names of source files located in a unit start from the unit name sep
 Thus, the names of files containing sources of C++ classes that belong to a package are constructed according to the following template:
 
 ~~~~~
-    <package-name>_<class-name>.cxx (or .hxx, or .cdl)
+    <package-name>_<class-name>.cxx (or .hxx)
 ~~~~~
 
 For example, file *Adaptor2d_Curve2d.cxx* belongs to the package *Adaptor2d*
@@ -459,12 +459,12 @@ The comments should be compatible with Doxygen tool for automatic documentation
 
 ### Documenting classes [MANDATORY]
 
-Each class should be documented in its header file (.hxx or .cdl).
+Each class should be documented in its header file (.hxx).
 The comment should give enough details for the reader to understand the purpose of the class and the main way of work with it.
 
 ### Documenting class methods [MANDATORY]
 
-Each class or package method should be documented in the header file (.hxx or .cdl).
+Each class or package method should be documented in the header file (.hxx).
 
 The comment should explain the purpose of the method, its parameters, and returned value(s).
 Accepted style is:
@@ -690,72 +690,36 @@ Take care about cycling of handled references to avoid chains, which will never
 
 See the following example:
 
-In *MyPackage.cdl* :
+~~~~{.cpp}
+    class Slave;
 
-~~~~
-    class MyFirstHandle;
-    class MySecondHandle;
-    pointer MySecondPointer to MySecondHandle;
-    ...
-~~~~
-
-In *MyPackage_MyFirstHandle.cdl* :
-
-~~~~
-    class MyFirstHandle from MyPackage
-    ...
-    is
-    ...
-      SetSecondHandleA (me: mutable; theSecond: MySecondHandle from MyPackage);
-      SetSecondHandleB (me: mutable; theSecond: MySecondHandle from MyPackage);
+    class Master : public Standard_Transient
+    {
     ...
-    fields
+      void SetSlave (const Handle(Slave)& theSlave)
+      { 
+        mySlave = theSlave;
+      }
     ...
-      mySecondHandle  : MySecondHandle  from MyPackage;
-      mySecondPointer : MySecondPointer from MyPackage;
+    private:
+      Handle(Slave) theSlave; // smart pointer
     ...
-    end MyFirstHandle from MyPackage;
-~~~~
-
-In *MyPackage_MySecondHandle.cdl* :
+    }
 
-~~~~
-    class MySecondHandle from MyPackage
-    ...
-    is
-    ...
-      SetFirstHandle (me: mutable; theFirst: MyFirstHandle from MyPackage);
+    class Slave : public Standard_Transient
+    {
     ...
-    fields
+      void SetMaster (const Handle(Master)& theMaster)
+      { 
+        myMaster = theMaster.get();
+      }
     ...
-      myFirstHandle : MyFirstHandle from MyPackage;
+    private:
+      Master* theMaster; // simple pointer
     ...
-    end MySecondHandle from MyPackage;
+    }
 ~~~~
 
-In C++ code:
-
-~~~~~{.cpp}
-void MyFunction()
-{
-  Handle(MyPackage_MyFirstHandle)  anObj1 = new MyPackage_MyFirstHandle();
-  Handle(MyPackage_MySecondHandle) anObj2 = new MyPackage_MySecondHandle();
-  Handle(MyPackage_MySecondHandle) anObj3 = new MyPackage_MySecondHandle();
-
-  anObj1->SetSecondHandleA(anObj2);
-  anObj1->SetSecondHandleB(anObj3);
-  anObj2->SetFirstHandle(anObj1);
-  anObj3->SetFirstHandle(anObj1);
-
-  // memory is not freed here !!!
-  anObj1.Nullify();
-  anObj2.Nullify();
-
-  // memory is freed here
-  anObj3.Nullify();
-}
-~~~~~
-
 ### C++ memory allocation
 
 In C++ use *new* and *delete* operators instead of *malloc()* and *free()*. Try not to mix different memory allocation techniques.
index 6d13400..5abb1f8 100644 (file)
@@ -2153,7 +2153,8 @@ The package consists of the following classes:
 
 @figure{/user_guides/boolean_operations/images/operations_image065.svg, "Diagram of BRepAlgoAPI package"} 
 
-The detailed description of the classes can be found in corresponding .cdl files. The examples are below in this chapter.
+The detailed description of the classes can be found in corresponding header files.
+The examples are below in this chapter.
 
 @subsection occt_algorithms_11b_2 Package BOPTest
 The package *BOPTest* provides the usage of the Boolean Component on Tcl level. The method *BOPTest::APICommands* contains corresponding Tcl commands: 
index d2c9733..688a3a8 100644 (file)
@@ -79,7 +79,7 @@ Test Harness executable *DRAWEXE* is located in the <i>$CASROOT/\<platform\>/bin
 
 Open CASCADE Technology is shipped with the DrawPlugin resource file located in the <i>$CASROOT/src/DrawResources</i> directory. 
 
-The format of the file is compliant with standard Open CASCADE Technology resource files (see the *Resource_Manager.cdl* file for details). 
+The format of the file is compliant with standard Open CASCADE Technology resource files (see the *Resource_Manager.hxx* file for details). 
 
 Each key defines a sequence of either further (nested) keys or a name of the dynamic library. Keys can be nested down to an arbitrary level. However, cyclic dependencies between the keys are not checked. 
 
@@ -9949,7 +9949,7 @@ DPLUGIN(MyPack)
 
 @subsection occt_draw_11_4 Creation of the plug-in resource file
 
-As mentioned above, the plug-in resource file must be compliant with Open CASCADE Technology requirements (see *Resource_Manager.cdl* file for details). In particular, it should contain keys separated from their values by a colon (;:;). 
+As mentioned above, the plug-in resource file must be compliant with Open CASCADE Technology requirements (see *Resource_Manager.hxx* file for details). In particular, it should contain keys separated from their values by a colon (;:;). 
 For every created plug-in there must be a key. For better readability and comprehension it is recommended to have some meaningful name. 
 Thus, the resource file must contain a line mapping this name (key) to the library name. The latter should be without file extension (.dll on Windows, .so on Unix/Linux) and without the ;lib; prefix on Unix/Linux. 
 For several plug-ins one resource file can be created. In such case, keys denoting plug-ins can be combined into groups, these groups -- into their groups and so on (thereby creating some hierarchy). Any new parent key must have its value as a sequence of child keys separated by spaces, tabs or commas. Keys should form a tree without cyclic dependencies. 
index 977892d..fe573c6 100644 (file)
@@ -261,8 +261,8 @@ Open CASCADE Technology  provides preprocessor macro *Handle()* that is historic
 Handle(Geom_Line) aLine; // "Handle(Geom_Line)" is expanded to "opencascade::handleL<Geom_Line>"
 ~~~~~
 
-In addition, for standard OCCT classes additional typedef is defined for a handle, as name of a class prefixed by *Handle_*.
-For instance, above example can be also coded as:
+In addition, for standard OCCT classes additional *typedef* is defined for a handle, as the name of a class prefixed by *Handle_*.
+For instance, the above example can be also coded as:
 ~~~~~{.cpp}
 Handle_Geom_Line aLine; // "Handle_Geom_Line" is typedef to "opencascade::handleL<Geom_Line>"
 ~~~~~
@@ -286,10 +286,10 @@ To initialize a handle, either a new object should be  created or the value of a
 
 Open CASCADE Technology provides a means to describe the hierarchy  of data types in a generic way, with a possibility to check the exact type of  the given object at run-time (similarly to C++ RTTI). 
 
-To enable this feature, a class declaration should include declaration of OCCT RTTI.
+To enable this feature, a class declaration should include the declaration of OCCT RTTI.
 Header *Standard_Type.hxx* provides two variants of preprocessor macros facilitating this:
 
-* Inline variant, declares and defines RTTI methods by single line of code:
+* Inline variant, which declares and defines RTTI methods by a single line of code:
 ~~~~~{.cpp}
 #include <Geom_Surface.hxx>
 class Appli_ExtSurface : public Geom_Surface
@@ -300,7 +300,7 @@ public:
 };
 ~~~~~
 
-* Out-of line variant, using one macros in declaration (normally put in header file), and another for implementation (to be put in C++ source):
+* Out-of line variant, which uses one macro in the declaration (normally in the header file), and another in the implementation (in C++ source):
 
   In *Appli_ExtSurface.hxx* file:
 ~~~~~{.cpp}
@@ -320,11 +320,11 @@ IMPLEMENT_STANDARD_RTTIEXT(Appli_ExtSurface,Geom_Surface)
 ~~~~~
 
 These macros define method *DynamicType()* that returns a type descriptor - handle to singleton instance of the class *Standard_Type* describing the class.
-Type descriptor stores name of the class and descriptor of its parent class.
+The type descriptor stores the name of the class and the descriptor of its parent class.
 
 Note that while inline version is easier to use, for widely used classes this method may lead to bloating of binary code of dependent libraries, due to multiple instantiations of inline method.
 
-To get the type descriptor for a given class type, use macros *STANDARD_TYPE()* with name of the class as argument.
+To get the type descriptor for a given class type, use macro *STANDARD_TYPE()* with the name of the class as argument.
 
 Example of usage:
 ~~~~~{.cpp}
@@ -370,7 +370,7 @@ If conversion is not compatible with the actual type of the  referenced object,
 ~~~~~~
 void MyFunction (const Handle(A) & a)
 {
-  Handle(B) b =  Handle(B)::Downcast(a);
+  Handle(B) b =  Handle(B)::DownCast(a);
   if (! b.IsNull()) {
     // we can use â€œb” if class B inherits from A
   }
@@ -1317,21 +1317,21 @@ IMPLEMENT_HSEQUENCE (MyPackage_HSequenceOfPnt)
 @subsubsection occt_fcug_3_3_3 Arrays and sequences
 
 Standard collections provided by OCCT are:
-* *NCollection_Array1* - fixed-size (at initialization) one-dimensional array; note that index can start at any value, usually 1
-* *NCollection_Array2* - fixed-size (at initialization) two-dimensional array; note that index can start at any value, usually 1
-* *NCollection_List* - plain list
-* *NCollection_Sequence* - double-connected list with access by index; note that index starts at 1
+* *NCollection_Array1* -- fixed-size (at initialization) one-dimensional array; note that the index can start at any value, usually 1;
+* *NCollection_Array2* -- fixed-size (at initialization) two-dimensional array; note that the index can start at any value, usually 1;
+* *NCollection_List* -- plain list;
+* *NCollection_Sequence* -- double-connected list with access by index; note that the index starts at 1.
 
 These classes provide STL-style iterators (methods begin() and end()) and thus can be used in STL algorithms.
 
 @subsubsection occt_fcug_3_3_3x Maps
 
 NCollection provides several classes for storage of objects by value, providing fast search due to use of hash:
-* *NCollection_Map* - hash set
-* *NCollection_IndexedMap* - set with prefixed order of elements, allowing fast access by index or by value (hash-based)
-* *NCollection_DataMap* - hash map
-* *NCollection_IndexedDataMap* - map with prefixed order of elements, allowing fast access by index or by value (hash-based)
-* *NCollection_DoubleMap* - two-side hash map (with two keys)
+* *NCollection_Map* -- hash set;
+* *NCollection_IndexedMap* -- set with a prefixed order of elements, allowing fast access by index or by value (hash-based);
+* *NCollection_DataMap* -- hash map;
+* *NCollection_IndexedDataMap* -- map with a prefixed order of elements, allowing fast access by index or by value (hash-based);
+* *NCollection_DoubleMap* -- two-side hash map (with two keys).
 
 @subsubsection occt_fcug_3_3_4 Other collection types
 
index 6c58138..c3e66c9 100644 (file)
@@ -672,29 +672,7 @@ NewDocumentFormat.AttributeStoragePlugin:57b0b826-d931-11d1-b5da-00a0c9064368
 NewDocumentFormat.AttributeRetrievalPlugin:57b0b827-d931-11d1-b5da-00a0c9064368 
 ~~~~~
 
-* Create the resource file "Plugin" with GUIDs and corresponding plugin libraries, which looks like this:
-
-**Example** 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-! Description of available plugins 
-! ************ 
-b148e300-5740-11d1-a904-080036aaa103.Location: libFWOSPlugin.so 
-! 
-! standard document drivers plugin 
-! 
-bd696000-5b34-11d1-b5ba-00a0c9064368.Location: libPAppStdPlugin.so 
-bd696001-5b34-11d1-b5ba-00a0c9064368.Location: libPAppStdPlugin.so 
-! 
-! standard schema plugin 
-! 
-bd696002-5b34-11d1-b5ba-00a0c9064368.Location: libPAppStdPlugin.so 
-! 
-! standard attribute drivers plugin 
-! 
-57b0b826-d931-11d1-b5da-00a0c9064368.Location: libPAppStdPlugin.so 
-57b0b827-d931-11d1-b5da-00a0c9064368.Location: libPAppStdPlugin.so 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Copy the resource file "Plugin" from $CASROOT/src/StdResource
 
 In order to set the paths for these files it is necessary to set the environments: *CSF_PluginDefaults* and *CSF_NewFormatDefaults*. For example, set the files in the directory *MyApplicationPath/MyResources*: 
 
@@ -703,14 +681,7 @@ setenv CSF_PluginDefaults MyApplicationPath/MyResources
 setenv CSF_NewFormatDefaults MyApplicationPath/MyResources 
 ~~~~~
 
-Once these steps are taken you may run your application, create documents and Save/Open them. These resource files already exist in the OCAF (format "Standard"). 
-
-If you use your specific attributes from packages, for example, <i>P-, M-</i> and *TMyAttributePackage*  (see @ref occt_ocaf_3_5_6  "Specific attribute creation") you must take some additional steps for the new plugin implementation: 
-
-1. Add our *P* package to the standard schema. You can get an already existing (in Open CASCADE Technology sources) schema from *StdSchema* unit and add your package string to the cdl-file: package  *PMyAttributePackage*.
-2. The next step consists in the implementation of an executable, which will connect our documents to our application and open/save them. Copy the package *PAppStdPlugin* and change its name to *MyTheBestApplicationPlugin*. In the *PLUGIN* macros type the name of your factory, which will be defined at the next step.
-3. *Factory* is a method, which returns drivers (standard drivers and our defined drivers from the *M* package) by a GUID. Copy the package to the location, where the standard factory is defined (it is PAppStd in the OCAF sources). Change its name to *MyTheBestSchemaLocation*. The *Factory()* method of the *PappStd* package checks the GUID set as its argument and returns the corresponding table of drivers. Set two new GUIDs for your determined storage and retrieval drivers. Append two *if* declarations inside the *Factory()* method, which should check whether the set GUID coincides with GUIDs defined by the *Factory()* method as far as our storage and retrieval drivers are concerned. If the GUID coincides with one of them, the method should return a table of storage or retrieval drivers respectively.
-4. Recompile all and add the strings with GUIDs  to the *Plugin* file in accordance with your plugin library GUID.
+Once these steps are taken you may run your application, create documents and Save/Open them.
 
 @subsubsection occt_ocaf_4_3_4 Opening the document from a file