Finalize code cleaning and documentation

CURA-12361

Author: wawanbreton

doc/bridging_skin_support.svg

@@ -85,6 +85,13 @@ class LayerPlanBuffer
      */
     void flush();
 
+    /*!
+     * Gets the layer plan for the given layer, once it has been completed. It will wait for completion if necessary
+     * @param layer_nr The layer number to get the plan for
+     * @return The completed layer plan
+     * @warning Make sure you always ask for a layer plan below the one that is being processed. Since the layers processing is started bottom to top and the engine can be run
+     *          mono-threaded, asking for a layer above could lead to a deadlock because the processing of this layer will never start.
+     */
     const LayerPlan* getCompletedLayerPlan(const LayerIndex& layer_nr) const;
 
 private:

include/LayerPlanBuffer.h

@@ -32,7 +32,6 @@ namespace cura
 {
 
 class Point3LL;
-class AngleRadians;
 
 /* 64bit Points are used mostly throughout the code, these are the 2D points from ClipperLib */
 using Point2LL = ClipperLib::IntPoint;
@@ -195,8 +194,6 @@ INLINE coord_t cross(const Point2LL& p0, const Point2LL& p1)
     return p0.X * p1.Y - p0.Y * p1.X;
 }
 
-AngleRadians vAngle(const Point2LL& vector);
-
 // Identity function, used to be able to make templated algorithms where the input is sometimes points, sometimes things that contain or can be converted to points.
 INLINE const Point2LL& make_point(const Point2LL& p)
 {
@@ -220,6 +217,7 @@ inline Point2LL lerp(const Point2LL& a, const Point2LL& b, const double t)
     return Point2LL(lerp(a.X, b.X, t), lerp(a.Y, b.Y, t));
 }
 
+/*! Returns true if the points are equal or close enough to each other to be considered equal */
 inline bool fuzzy_equal(const Point2LL& a, const Point2LL& b)
 {
     return fuzzy_equal(a.X, b.X) && fuzzy_equal(a.Y, b.Y);

include/geometry/Point2LL.h

@@ -73,15 +73,9 @@ class PointsSet
         return points_.size();
     }
 
-    bool push_back(const Point2LL& point, const bool only_if_forming_segment = false)
+    void push_back(const Point2LL& point)
     {
-        if (only_if_forming_segment && ! points_.empty() && fuzzy_equal(point, points_.back()))
-        {
-            return false;
-        }
-
         points_.push_back(point);
-        return true;
     }
 
     /*! \brief Pushes an entire set at the end */

include/geometry/PointsSet.h

@@ -90,11 +90,6 @@ class Polygon : public ClosedPolyline
         return ClipperLib::Area(getPoints());
     }
 
-    [[nodiscard]] bool isHole() const
-    {
-        return area() < 0.0;
-    }
-
     [[nodiscard]] Point2LL centerOfMass() const;
 
     [[nodiscard]] Shape offset(int distance, ClipperLib::JoinType join_type = ClipperLib::jtMiter, double miter_limit = 1.2) const;

include/geometry/Polygon.h

@@ -130,6 +130,23 @@ class Polyline : public PointsSet
 
     [[nodiscard]] bool shorterThan(const coord_t check_length) const;
 
+    /*!
+     * Adds a point to this set, but only if it forms a proper new segment i.r.t the current points in the set
+     * @param point The point to be added
+     * @return True if the point has actually been added, false otherwise
+     * @note The point will also be added if the current list is empty
+     */
+    bool pushBackIfFormingSegment(const Point2LL& point)
+    {
+        if (getPoints().empty() || ! fuzzy_equal(point, getPoints().back()))
+        {
+            push_back(point);
+            return true;
+        }
+
+        return false;
+    }
+
     void reverse()
     {
         ClipperLib::ReversePath(getPoints());

include/geometry/Polyline.h

@@ -105,12 +105,12 @@ class AngleRadians
     /*
      * \brief Default constructor setting the angle to 0.
      */
-    constexpr AngleRadians() noexcept = default;
+    AngleRadians() noexcept = default;
 
     /*!
      * \brief Converts an angle from degrees into radians.
      */
-    constexpr AngleRadians(const AngleDegrees& value);
+    AngleRadians(const AngleDegrees& value);
 
     /*
      * \brief Translate the double value in degrees to an AngleRadians instance.
@@ -166,16 +166,11 @@ inline AngleDegrees::AngleDegrees(const AngleRadians& value)
 {
 }
 
-constexpr inline AngleRadians::AngleRadians(const AngleDegrees& value)
+inline AngleRadians::AngleRadians(const AngleDegrees& value)
     : value_(value.value_ * TAU / 360.0)
 {
 }
 
-inline double normalizeTo(const double angle, const double max)
-{
-    return std::fmod(std::fmod(angle, max) + max, max);
-}
-
 /*!
  * \brief Safe call to "std::tan" which limits the higher angle value to something slightly less that π/2 so that when
  *        the given angle is higher that this value, the returned value is not a huge number
@@ -189,14 +184,6 @@ inline double boundedTan(const AngleRadians& angle)
     return std::tan(std::min(static_cast<double>(angle), std::numbers::pi / 2.0 - 0.001));
 }
 
-inline AngleDegrees nonOrientedDelta(const AngleDegrees& angle1, const AngleDegrees& angle2)
-{
-    const double normalized_angle1 = normalizeTo(angle1.value_, 180);
-    const double normalized_angle2 = normalizeTo(angle2.value_, 180);
-    const double diff = std::fabs(normalized_angle1 - normalized_angle2);
-    return std::min(diff, 180.0 - diff);
-}
-
 } // namespace cura
 
 #endif // ANGLE_H

include/settings/types/Angle.h

@@ -38,36 +38,43 @@ template<utils::floating_point FactorType>
     return std::llrint(std::lerp(static_cast<double>(a), static_cast<double>(b), t));
 }
 
+/*! Returns true if the given value is null or small enough to be considered null */
 [[nodiscard]] inline bool fuzzy_is_null(const coord_t value)
 {
     return std::abs(value) <= EPSILON;
 }
 
+/*! Returns true if the given values are equal or close enough to be considered equal */
 [[nodiscard]] inline bool fuzzy_equal(const coord_t a, const coord_t b)
 {
     return fuzzy_is_null(b - a);
 }
 
+/*! Returns true if the given values are not equal and different enough to be considered not equal */
 [[nodiscard]] inline bool fuzzy_not_equal(const coord_t a, const coord_t b)
 {
     return ! fuzzy_equal(a, b);
 }
 
+/*! Returns true if the given \a value is greater enough to \b to be considered greater */
 [[nodiscard]] inline bool fuzzy_is_greater(const coord_t a, const coord_t b)
 {
     return a - b > EPSILON;
 }
 
+/*! Returns true if the given \a value is greater or close enough to \b to be considered greater or equal */
 [[nodiscard]] inline bool fuzzy_is_greater_or_equal(const coord_t a, const coord_t b)
 {
     return a > b - EPSILON;
 }
 
+/*! Returns true if the given \a value is lesser enough to \b to be considered lesser */
 [[nodiscard]] inline bool fuzzy_is_lesser(const coord_t a, const coord_t b)
 {
     return b - a > EPSILON;
 }
 
+/*! Returns true if the given \a value is lesser or close enough to \b to be considered lesser or equal */
 [[nodiscard]] inline bool fuzzy_is_lesser_or_equal(const coord_t a, const coord_t b)
 {
     return b > a - EPSILON;

include/utils/Coord_t.h

@@ -86,8 +86,22 @@ class LinearAlg2D
 
     static bool lineLineIntersection(const Point2LL& a, const Point2LL& b, const Point2LL& c, const Point2LL& d, Point2LL& output);
 
+    /*!
+     * Computes the intersection between a line and a horizontal line
+     * @param p1 One point on the line
+     * @param p2 An other point on the line
+     * @param line_y The Y coordinates of the horizontal line to intersect with
+     * @return The x coordinate of the intersection, or nullopt if they don't intersect
+     */
     static std::optional<coord_t> lineHorizontalLineIntersection(const Point2LL& p1, const Point2LL& p2, const coord_t line_y);
 
+    /*!
+     * Computes the intersection between a segment and a horizontal line
+     * @param p1 The segment start point
+     * @param p2 The segment end point
+     * @param line_y The Y coordinates of the horizontal line to intersect with
+     * @return The x coordinate of the intersection, or nullopt if they don't intersect
+     */
     static std::optional<coord_t> segmentHorizontalLineIntersection(const Point2LL& p1, const Point2LL& p2, const coord_t line_y);
 
     /*!

include/utils/linearAlg2D.h

@@ -143,6 +143,10 @@ template<utils::floating_point T>
     return std::abs(value) < (std::numeric_limits<T>::epsilon() * 100.0);
 }
 
+/*!
+ * Calculates the sign of a numeric value, 1 if positive and -1 if negative
+ * @note 0 is also considered as positive
+ */
 template<utils::numeric T>
 [[nodiscard]] int8_t sign(T value)
 {