Comments for CSG stack ops

src/libslic3r/CSGMesh/CSGMesh.hpp

@@ -18,6 +18,23 @@ namespace Slic3r { namespace csg {
 
 // Supported CSG operation types
 enum class CSGType { Union, Difference, Intersection };
+
+// A CSG part can instruct the processing to push the sub-result until a new
+// csg part with a pop instruction appears. This can be used to implement
+// parentheses in a CSG expression represented by the collection of csg parts.
+// A CSG part can not contain another CSG collection, only a mesh, this is why
+// its easier to do this stacking instead of recursion in the data definition.
+// CSGStackOp::Continue means no stack operation required.
+// When a CSG part contains a Push instruction, it is expected that the CSG
+// operation it contains refers to the whole collection spanning to the nearest
+// part with a Pop instruction.
+// e.g.:
+// {
+//      CUBE1: { mesh: cube, op: Union, stack op: Continue },
+//      CUBE2: { mesh: cube, op: Difference, stack op: Push},
+//      CUBE3: { mesh: cube, op: Union, stack op: Pop}
+// }
+// is a collection of csg parts representing the expression CUBE1 - (CUBE2 + CUBE3)
 enum class CSGStackOp { Push, Continue, Pop };
 
 // Get the CSG operation of the part. Can be overriden for any type
@@ -26,6 +43,7 @@ template<class CSGPartT> CSGType get_operation(const CSGPartT &part)
     return part.operation;
 }
 
+// Get the stack operation required by the CSG part.
 template<class CSGPartT> CSGStackOp get_stack_operation(const CSGPartT &part)
 {
     return part.stack_operation;

src/libslic3r/CSGMesh/ModelToCSGMesh.hpp

@@ -9,18 +9,20 @@
 
 namespace Slic3r { namespace csg {
 
+// Flags to select which parts to export from Model into a csg part collection.
+// These flags can be chained with the | operator
 enum ModelParts {
-    mpartsPositive = 1,
+    mpartsPositive = 1,     // Include positive parts
-    mpartsNegative = 2,
+    mpartsNegative = 2,     // Include negative parts
-    mpartsDrillHoles = 4,
+    mpartsDrillHoles = 4,   // Include drill holes
-    mpartsDoSplits = 8
+    mpartsDoSplits = 8      // Split each splitable mesh and export as a union of csg parts
 };
 
 template<class OutIt>
 void model_to_csgmesh(const ModelObject &mo,
-                      const Transform3d &trafo,
+                      const Transform3d &trafo, // Applies to all exported parts
-                      OutIt              out,
+                      OutIt              out,   // Output iterator
-                      // values of ModelParts ORed
+                      // values of ModelParts OR-ed
                       int                parts_to_include = mpartsPositive
                       )
 {

src/libslic3r/CSGMesh/PerformCSGMeshBooleans.hpp

@@ -82,6 +82,7 @@ std::vector<CGALMeshPtr> get_cgalptrs(Ex policy, const Range<It> &csgrange)
 
 } // namespace detail
 
+// Process the sequence of CSG parts with CGAL.
 template<class It>
 void perform_csgmesh_booleans(MeshBoolean::cgal::CGALMeshPtr &cgalm,
                               const Range<It>                &csgrange)