From 15d4e122593d481f638c1f56c28c7653762ca10c Mon Sep 17 00:00:00 2001
From: Erwan MATHIEU <erwan.mathieu@ultimaker.com>
Date: Fri, 28 Jun 2024 11:30:41 +0200
Subject: [PATCH] Add/fix documentation

---
 include/PrimeTower/PrimeTower.h            | 14 +++++++++++---
 include/PrimeTower/PrimeTowerInterleaved.h |  8 ++++++++
 include/PrimeTower/PrimeTowerNormal.h      |  7 +++++++
 include/utils/LayerVector.h                |  2 +-
 4 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/include/PrimeTower/PrimeTower.h b/include/PrimeTower/PrimeTower.h
index 0c8343d48e..e0bbf5d5a6 100644
--- a/include/PrimeTower/PrimeTower.h
+++ b/include/PrimeTower/PrimeTower.h
@@ -22,10 +22,18 @@ class SliceDataStorage;
 class LayerPlan;
 
 /*!
- * Class for everything to do with the prime tower:
- * - Generating the areas.
+ * Abstract class for everything to do with the prime tower:
+ * - Generating the occupation areas.
  * - Checking up untill which height the prime tower has to be printed.
- * - Generating the paths and adding them to the layer plan.
+ * - Inserting priming commands in extruders uses
+ * - Generating priming paths and adding them to the layer plan.
+ *
+ * We may adopt different strategies to generate the prime tower, thus this class is abstract and different
+ * implementations may co-exist. The common behavior implemented in the main class is:
+ * - Generate occupation areas as a cylinder with a flared base
+ * - Generate the base extra extrusion discs around the base cylinder
+ * - Generate the first layer extra inset inside the base cylinder
+ * Then it is the job of the specific implementation to handle the generation of extrusion paths for the base cylinder
  */
 class PrimeTower
 {
diff --git a/include/PrimeTower/PrimeTowerInterleaved.h b/include/PrimeTower/PrimeTowerInterleaved.h
index 45d06b1aca..d9d743ca4c 100644
--- a/include/PrimeTower/PrimeTowerInterleaved.h
+++ b/include/PrimeTower/PrimeTowerInterleaved.h
@@ -9,6 +9,14 @@
 namespace cura
 {
 
+/*!
+ * Specific prime tower implementation that generates interleaved priming paths. It is optimized to waste as few
+ * filament as possible, while ensuring that the prime tower is still robust even if it gets very high.
+ * When there is no actual priming required for extruders, it will create a kind of circular zigzag pattern that acts as
+ * a sparse support. Otherwise it will create priming annuli, stacked on top of each other.
+ * This is very effective when doing multi-color printing, however it can be used only if all the filaments properly
+ * adhere to each other. Otherwise there is a high risk that the tower will collapse during the print.
+ */
 class PrimeTowerInterleaved : public PrimeTower
 {
 public:
diff --git a/include/PrimeTower/PrimeTowerNormal.h b/include/PrimeTower/PrimeTowerNormal.h
index 3037255e93..5235774252 100644
--- a/include/PrimeTower/PrimeTowerNormal.h
+++ b/include/PrimeTower/PrimeTowerNormal.h
@@ -9,6 +9,13 @@
 namespace cura
 {
 
+/*!
+ * Specific prime tower implementation that generates nested cylinders. Each layer, all the extruders will be used to
+ * contribute to the prime tower, even if they don't actually need priming. In this case, a circular zigzag pattern will
+ * be used to act as support for upper priming extrusions.
+ * Although this method is not very efficient, it is required when using different materials that don't properly adhere
+ * to each other. By nesting the cylinders, you make sure that the tower remains consistent and strong along the print.
+ */
 class PrimeTowerNormal : public PrimeTower
 {
 public:
diff --git a/include/utils/LayerVector.h b/include/utils/LayerVector.h
index d03aa9b50d..929f916297 100644
--- a/include/utils/LayerVector.h
+++ b/include/utils/LayerVector.h
@@ -14,7 +14,7 @@ namespace cura
 
 /*!
  * \brief The LayerVector class mimics a std::vector but with the index being a LayerIndex, thus it can have negative
- *        values (for raft layers). it also ensure that the first element in the list is always on the very first layer.
+ *        values (for raft layers). It also ensures that the first element in the list is always on the very first layer.
  * \note When calling the init() method, LayerVector will call Raft::getTotalExtraLayers() so it requires the settings
  *       to be setup. This is the reason why this is not done in the constructor, and has to be called manually.
  *       After that, it is assumed that this value will not change as long as the vector is used.