From 690757a38217c051f9811273ec03aedf89142fc9 Mon Sep 17 00:00:00 2001 From: kgv Date: Thu, 17 Jun 2021 20:11:09 +0300 Subject: [PATCH] 0032453: Documentation - nested multiline comments within BOPAlgo_CellsBuilder.hxx destroy Java wrapping --- src/BOPAlgo/BOPAlgo_CellsBuilder.hxx | 216 +++++++++++++-------------- 1 file changed, 107 insertions(+), 109 deletions(-) diff --git a/src/BOPAlgo/BOPAlgo_CellsBuilder.hxx b/src/BOPAlgo/BOPAlgo_CellsBuilder.hxx index c9183fa730..02d0022101 100644 --- a/src/BOPAlgo/BOPAlgo_CellsBuilder.hxx +++ b/src/BOPAlgo/BOPAlgo_CellsBuilder.hxx @@ -32,64 +32,60 @@ #include #include +//! The algorithm is based on the General Fuse algorithm (GFA). +//! The result of GFA is all split parts of the Arguments. //! -//! The algorithm is based on the General Fuse algorithm (GFA). The result of -//! GFA is all split parts of the Arguments.
+//! The purpose of this algorithm is to provide the result with the content of: +//! 1. Cells (parts) defined by the user; +//! 2. Internal boundaries defined by the user. //! -//! The purpose of this algorithm is to provide the result with the content of:
-//! 1. Cells (parts) defined by the user;
-//! 2. Internal boundaries defined by the user.
+//! In other words the algorithm should provide the possibility for the user to add +//! or remove any part to (from) result and remove any internal boundaries between parts. //! -//! In other words the algorithm should provide the possibility for the user -//! to add or remove any part to (from) result and remove any internal boundaries -//! between parts.
+//! All the requirements of GFA for the DATA are inherited in this algorithm. +//! The arguments could be of any type (dimension) and should be valid +//! in terms of BRepCheck_Analyzer and BOPAlgo_ArgumentAnalyzer. //! -//! Requirements for the Data:
-//! All the requirements of GFA for the DATA are inherited in this algorithm - -//! The arguments could be of any type (dimension) and should be valid in terms of -//! BRepCheck_Analyzer and BOPAlgo_ArgumentAnalyzer.
+//! Results: //! -//! Results:
-//! The result of the algorithm is compound containing selected parts of -//! the basic types (VERTEX, EDGE, FACE or SOLID). The default result -//! is empty compound. It is possible to add any split part to the result -//! by using the methods AddToRessult() and AddAllToResult(). -//! It is also possible to remove any part from the result by using methods -//! RemoveFromResult() and RemoveAllFromResult(). -//! The method RemoveAllFromResult() is also suitable for clearing the result.
+//! The result of the algorithm is compound containing selected parts of the basic types (VERTEX, EDGE, FACE or SOLID). +//! The default result is empty compound. +//! It is possible to add any split part to the result by using the methods AddToRessult() and AddAllToResult(). +//! It is also possible to remove any part from the result by using methods RemoveFromResult() and RemoveAllFromResult(). +//! The method RemoveAllFromResult() is also suitable for clearing the result. //! //! To remove Internal boundaries it is necessary to set the same material to the -//! parts between which the boundaries should be removed and call the method -//! RemoveInternalBoundaries(). The material should not be equal to 0, as this is -//! default material value. The boundaries between parts with this value -//! will not be removed. +//! parts between which the boundaries should be removed and call the method RemoveInternalBoundaries(). +//! The material should not be equal to 0, as this is default material value. +//! The boundaries between parts with this value will not be removed. //! One part cannot be added with the different materials. //! It is also possible to remove the boundaries during combining the result. -//! To do this it is necessary to set the material for parts (not equal to 0) -//! and set the flag bUpdate to TRUE. +//! To do this it is necessary to set the material for parts (not equal to 0) and set the flag bUpdate to TRUE. //! For the arguments of the types FACE or EDGE it is recommended //! to remove the boundaries in the end when the result is completely built. -//! It will help to avoid self-intersections in the result.
+//! It will help to avoid self-intersections in the result. +//! //! Note, that if the result contains the parts with same material but of different -//! dimension the boundaries between such parts will not be removed. Currently, -//! the removal of the internal boundaries between multi-dimensional shapes is not supported.
+//! dimension the boundaries between such parts will not be removed. +//! Currently, the removal of the internal boundaries between multi-dimensional shapes is not supported. //! -//! It is possible to create typed Containers from the parts added to result by using -//! method MakeContainers(). The type of the containers will depend on the type of -//! the arguments: WIRES for EEDGE, SHELLS for FACES and COMPSOLIDS for SOLIDS. +//! It is possible to create typed Containers from the parts added to result by using method MakeContainers(). +//! The type of the containers will depend on the type of the arguments: +//! WIRES for EEDGE, SHELLS for FACES and COMPSOLIDS for SOLIDS. //! The result will be compound containing containers. -//! Adding of the parts to such result will not update containers. The result -//! compound will contain the containers and new added parts (of basic type). +//! Adding of the parts to such result will not update containers. +//! The result compound will contain the containers and new added parts (of basic type). //! Removing of the parts from such result may affect some containers if -//! the parts that should be removed is in container. In this case this container -//! will be rebuilt without that part.
+//! the parts that should be removed is in container. +//! In this case this container will be rebuilt without that part. //! -//! History:
-//! The algorithm supports history information for basic types of the shapes - -//! VERTEX, EDGE, FACE. This information available through the methods -//! IsDeleted() and Modified().
-//! In DRAW Test Harness it is available through the same -//! commands as for Boolean Operations (bmodified, bgenerated and bisdeleted).
+//! History: +//! +//! The algorithm supports history information for basic types of the shapes - VERTEX, EDGE, FACE. +//! This information available through the methods IsDeleted() and Modified(). +//! +//! In DRAW Test Harness it is available through the same commands +//! as for Boolean Operations (bmodified, bgenerated and bisdeleted). //! //! The algorithm can return the following Error Statuses: //! - Error status acquired in the General Fuse algorithm. @@ -103,76 +99,78 @@ //! - BOPAlgo_AlertRemovalOfIBForEdgesFailed //! - BOPAlgo_AlertRemovalOfIBForSolidsFailed //! -//! The Warning status can be checked with HasWarnings() method or -//! printed with the DumpWarnings() method. If warnings are recorded, -//! the result may be not as expected.
+//! The Warning status can be checked with HasWarnings() method or printed with the DumpWarnings() method. +//! If warnings are recorded, the result may be not as expected. //! -//! Examples:
-//! 1. API
-//! BOPAlgo_CellsBuilder aCBuilder;
-//! TopTools_ListOfShape aLS = ...; // arguments
-//! /* parallel or single mode (the default value is FALSE)*/
-//! Standard_Boolean bRunParallel = Standard_False;
-//! /* fuzzy option (default value is 0)*/
-//! Standard_Real aTol = 0.0;
-//! //
-//! aCBuilder.SetArguments(aLS);
-//! aCBuilder.SetRunParallel(bRunParallel);
-//! aCBuilder.SetFuzzyValue(aTol);
-//! //
-//! aCBuilder.Perform();
-//! if (aCBuilder.HasErrors()) { // check error status
-//! return;
-//! }
-//! /* empty compound, as nothing has been added yet */
-//! const TopoDS_Shape& aRes = aCBuilder.Shape();
-//! /* all split parts */
-//! const TopoDS_Shape& aRes = aCBuilder.GetAllParts();
-//! //
-//! TopTools_ListOfShape aLSToTake = ...; // parts of these arguments will be taken into result
-//! TopTools_ListOfShape aLSToAvoid = ...; // parts of these arguments will not be taken into result
-//! //
-//! /* defines the material common for the cells, i.e. -//! the boundaries between cells with the same material -//! will be removed.
-//! By default it is set to 0. Thus, to remove some boundary -//! the value of this variable should not be equal to 0 */
-//! Standard_Integer iMaterial = ...;
-//! /* defines whether to update the result right now or not */
-//! Standard_Boolean bUpdate = ...;
-//! // adding to result
-//! aCBuilder.AddToResult(aLSToTake, aLSToAvoid, iMaterial, bUpdate);
-//! aR = aCBuilder.Shape(); // the result
-//! // removing of the boundaries (should be called only if bUpdate is false)
-//! aCBuilder.RemoveInternalBoundaries();
-//! //
-//! // removing from result
-//! aCBuilder.AddAllToResult();
-//! aCBuilder.RemoveFromResult(aLSToTake, aLSToAvoid);
-//! aR = aCBuilder.Shape(); // the result
-//!
+//! Examples: //! -//! 2. DRAW Test Harness
-//! psphere s1 15
-//! psphere s2 15
-//! psphere s3 15
-//! ttranslate s1 0 0 10
-//! ttranslate s2 20 0 10
-//! ttranslate s3 10 0 0
-//! \# adding arguments
-//! bclearobjects; bcleartools
-//! baddobjects s1 s2 s3
-//! \# intersection
-//! bfillds
-//! \# rx will contain all split parts
-//! bcbuild rx
-//! \# add to result the part that is common for all three spheres
-//! bcadd res s1 1 s2 1 s3 1 -m 1
-//! \# add to result the part that is common only for first and third spheres
-//! bcadd res s1 1 s2 0 s3 1 -m 1
-//! \# remove internal boundaries
-//! bcremoveint res
+//! 1. API +//! @code +//! BOPAlgo_CellsBuilder aCBuilder; +//! TopTools_ListOfShape aLS = ...; // arguments +//! // parallel or single mode (the default value is FALSE) +//! bool toRunParallel = false; +//! // fuzzy option (default value is 0) +//! Standard_Real aTol = 0.0; +//! // +//! aCBuilder.SetArguments (aLS); +//! aCBuilder.SetRunParallel (toRunParallel); +//! aCBuilder.SetFuzzyValue (aTol); +//! // +//! aCBuilder.Perform(); +//! if (aCBuilder.HasErrors()) // check error status +//! { +//! return; +//! } +//! // empty compound, as nothing has been added yet +//! const TopoDS_Shape& aRes = aCBuilder.Shape(); +//! // all split parts +//! const TopoDS_Shape& aRes = aCBuilder.GetAllParts(); +//! // +//! TopTools_ListOfShape aLSToTake = ...; // parts of these arguments will be taken into result +//! TopTools_ListOfShape aLSToAvoid = ...; // parts of these arguments will not be taken into result +//! // +//! // defines the material common for the cells, +//! // i.e. the boundaries between cells with the same material will be removed. +//! // By default it is set to 0. +//! // Thus, to remove some boundary the value of this variable should not be equal to 0. +//! Standard_Integer iMaterial = ...; +//! // defines whether to update the result right now or not +//! bool toUpdate = ...; +//! // adding to result +//! aCBuilder.AddToResult (aLSToTake, aLSToAvoid, iMaterial, toUpdate); +//! aR = aCBuilder.Shape(); // the result +//! // removing of the boundaries (should be called only if toUpdate is false) +//! aCBuilder.RemoveInternalBoundaries(); +//! // +//! // removing from result +//! aCBuilder.AddAllToResult(); +//! aCBuilder.RemoveFromResult (aLSToTake, aLSToAvoid); +//! aR = aCBuilder.Shape(); // the result +//! @endcode //! +//! 2. DRAW Test Harness +//! @code +//! psphere s1 15 +//! psphere s2 15 +//! psphere s3 15 +//! ttranslate s1 0 0 10 +//! ttranslate s2 20 0 10 +//! ttranslate s3 10 0 0 +//! # adding arguments +//! bclearobjects; bcleartools +//! baddobjects s1 s2 s3 +//! # intersection +//! bfillds +//! # rx will contain all split parts +//! bcbuild rx +//! # add to result the part that is common for all three spheres +//! bcadd res s1 1 s2 1 s3 1 -m 1 +//! # add to result the part that is common only for first and third spheres +//! bcadd res s1 1 s2 0 s3 1 -m 1 +//! # remove internal boundaries +//! bcremoveint res +//! @endcode class BOPAlgo_CellsBuilder : public BOPAlgo_Builder { public: