A bit more polygon docs

docs/src/general/changelog.md

@@ -6,7 +6,10 @@ description: |
 
 # Changelog
 ## Unreleased
-- Reduced maximum function call depth from 256 to 64.
+- Added [`polygon`]($func/polygon) function
+- Reduced maximum function call depth from 256 to 64
+- CLI now returns with non-zero status code if there is an error
+- CLI now watches the root directory instead of the current one
 
 ## March 28, 2023
 - **Breaking:** Enumerations now require a space after their marker, that is,

library/src/visualize/mod.rs

@@ -2,10 +2,10 @@
 
 mod image;
 mod line;
-mod shape;
 mod polygon;
+mod shape;
 
 pub use self::image::*;
 pub use self::line::*;
-pub use self::shape::*;
 pub use self::polygon::*;
+pub use self::shape::*;

library/src/visualize/polygon.rs

@@ -1,10 +1,19 @@
 use crate::prelude::*;
 
-/// A closed-path polygon.
+/// A closed polygon.
+///
+/// The polygon is defined by its corner points and is closed automatically.
 ///
 /// ## Example
 /// ```example
-/// #polygon(fill: blue, (0pt, 0pt), (10pt, 0pt), (10pt, 10pt))
+/// #polygon(
+///   fill: red,
+///   stroke: 2pt + black,
+///   (0pt, 0pt),
+///   (50%, 0pt),
+///   (50%, 4cm),
+///   (20%, 4cm),
+/// )
 /// ```
 ///
 /// Display: Polygon
@@ -13,6 +22,9 @@ use crate::prelude::*;
 pub struct PolygonElem {
     /// How to fill the polygon. See the
     /// [rectangle's documentation]($func/rect.fill) for more details.
+    ///
+    /// Currently all polygons are filled according to the
+    /// [non-zero winding rule](https://en.wikipedia.org/wiki/Nonzero-rule).
     pub fill: Option<Paint>,
 
     /// How to stroke the polygon. See the [lines's
@@ -21,7 +33,8 @@ pub struct PolygonElem {
     #[fold]
     pub stroke: Option<PartialStroke>,
 
-    /// The vertices of the polygon. The polygon automatically closes itself.
+    /// The vertices of the polygon. Each point is specified as an array of two
+    /// [relative lengths]($type/relative-length).
     #[variadic]
     pub vertices: Vec<Axes<Rel<Length>>>,
 }
@@ -45,20 +58,19 @@ impl Layout for PolygonElem {
             .collect();
 
         let size = points.iter().fold(Point::zero(), |max, c| c.max(max)).to_size();
-
         let target = regions.expand.select(regions.size, size);
         let mut frame = Frame::new(target);
 
-        // only create a path if there is more than zero points.
+        // Only create a path if there are more than zero points.
         if points.len() > 0 {
-            let stroke = self.stroke(styles).map(|e| e.unwrap_or_default());
             let fill = self.fill(styles);
+            let stroke = self.stroke(styles).map(PartialStroke::unwrap_or_default);
 
-            // construct a closed path given all points.
+            // Construct a closed path given all points.
             let mut path = Path::new();
             path.move_to(points[0]);
-            for point in &points[1..] {
+            for &point in &points[1..] {
-                path.line_to(*point);
+                path.line_to(point);
             }
             path.close_path();
 

tests/typ/visualize/polygon.typ

@@ -1,31 +1,32 @@
 // Test polygons.
 
 ---
-#set page(height: 220pt, width: 50pt)
+#set page(width: 50pt)
-#box({
+#set polygon(stroke: 0.75pt, fill: blue)
-  set polygon(stroke: 0.75pt, fill: blue)
+
-  polygon((0em, 0pt))
+// These are not visible, but should also not give an error
-  // this should not give an error
+#polygon()
-  polygon()
+#polygon((0em, 0pt))
-  polygon((0pt, 0pt), (10pt, 0pt))
+#polygon((0pt, 0pt), (10pt, 0pt))
-  polygon((5pt, 0pt), (0pt, 10pt), (10pt, 10pt))
+
-  polygon(
+#polygon((5pt, 0pt), (0pt, 10pt), (10pt, 10pt))
+#polygon(
   (0pt, 0pt), (5pt, 5pt), (10pt, 0pt),
   (15pt, 5pt),
   (5pt, 10pt)
-  )
+)
-  polygon(stroke: none, (5pt, 0pt), (0pt, 10pt), (10pt, 10pt))
+#polygon(stroke: none, (5pt, 0pt), (0pt, 10pt), (10pt, 10pt))
-  polygon(stroke: 3pt, fill: none, (5pt, 0pt), (0pt, 10pt), (10pt, 10pt))
+#polygon(stroke: 3pt, fill: none, (5pt, 0pt), (0pt, 10pt), (10pt, 10pt))
-  // relative size
+
-  polygon((0pt, 0pt), (100%, 5pt), (50%, 10pt))
+// Relative size
-  // antiparallelogram
+#polygon((0pt, 0pt), (100%, 5pt), (50%, 10pt))
-  polygon((0pt, 5pt), (5pt, 0pt), (0pt, 10pt), (5pt, 15pt))
+
-  // self-intersections
+// Antiparallelogram
-  polygon((0pt, 10pt), (30pt, 20pt), (0pt, 30pt), (20pt, 0pt), (20pt, 35pt))
+#polygon((0pt, 5pt), (5pt, 0pt), (0pt, 10pt), (5pt, 15pt))
-})
+
+// Self-intersections
+#polygon((0pt, 10pt), (30pt, 20pt), (0pt, 30pt), (20pt, 0pt), (20pt, 35pt))
 
 ---
-// Test errors.
-
 // Error: 10-17 point array must contain exactly two entries
 #polygon((50pt,))