figure: x axes follow the column structure; split rows keep the right gutter on the last cell only

include/plot/plot/figure.hpp

@@ -32,15 +32,16 @@ struct FigureLayout {
   /// rect here; a row of several tiles its rect left to right with `col_gap` between
   /// cells, the cells' widths summing to the row's less the gaps.
   std::vector<Rect> cells;
-  /// The strip the figure's one shared x axis is drawn in: the bottom row's own
+  /// The strip the figure's bottom x axis is drawn in: the bottom row's own
   /// `PlotLayout::x_label_area` (for a bottom row split into several cells, only the **last
   /// cell's** strip -- the others' strips are their own `plot(i).layout().x_label_area`, which
-  /// is where the controller's axis-zoom hit test reads each cell's gestures from), at the bottom of the bottom row's rect and so as
-  /// wide as that row's axes rather than the whole figure. Read back from the row
+  /// is where the controller's axis-zoom hit test reads each cell's gestures from), at the
+  /// bottom of the bottom row's rect and so as wide as that row's axes rather than the whole
+  /// figure. Read back from the row
   /// rather than derived here, so a host and the frame cannot disagree about where
   /// the axis is. It is nonzero whenever the figure has rows and the bottom row
-  /// reserves a label strip -- including the case where every row labels itself, in
-  /// which case it is simply the bottom row's own strip, one of several.
+  /// reserves a label strip. A row above whose columns differ from the row below keeps
+  /// a strip of its own (see `Figure`), which is its plots' `x_label_area`, not this.
   ///
   /// It is the rect the controller's axis-zoom hit test reads (`x_label_area` is what
   /// a middle drag in a label strip enters `DragMode::AxisZoomX` from), which is why
@@ -70,12 +71,15 @@ struct FigureLayout {
 /// **The shared x axis.** Row heights are an equal division of the figure by
 /// default, `set_row_weights()` gives a row more of it, and every row keeps a floor
 /// height so chrome can never erase a plot. When `set_x_labels_only_on_bottom()` is
-/// on -- the default -- the figure's one x axis is the **bottom row's own**: the rows
-/// above reserve no x chrome at all, and the bottom row keeps its own label and title
-/// strips, so those labels and that title are drawn once, from the bottom row's own
-/// ticks and transform. That places the shared axis *inside* a row, where the
-/// controller's axis-zoom hit test can reach it, instead of in a band outside every
-/// row that no gesture could land in.
+/// on -- the default -- the x axis is the **bottom row's own** for every run of rows
+/// with the *same columns* (the same number of cells and the same normalised cell
+/// weights): those rows above reserve no x chrome at all, and the bottom row of the run
+/// keeps its own label and title strips, so those labels and that title are drawn once,
+/// from its own ticks and transform. A row whose columns differ from the row below keeps
+/// its own strip, drawn under each of its cells, because the axis below is at another
+/// scale and width. The rule is structural, never a function of what a plot holds. That
+/// places a shared axis *inside* a row, where the controller's axis-zoom hit test can
+/// reach it, instead of in a band outside every row that no gesture could land in.
 ///
 /// **The x link.** `plot(i).set_x_range()` and a controller gesture both reach a
 /// member's x range the same way, so a figure cannot see either of them happen.
@@ -186,14 +190,17 @@ class Figure {
   /// than row by row for the left gutter's reason: the rows' axes have to line up, and
   /// they end on a common column only if they are told one width. See
   /// `Plot::set_right_gutter()` for what it is for. Negative values are clamped to 0.
+  /// In a split row whose cells share one y (`set_share_row_y`) only the **last** cell
+  /// keeps it, taken off the row like the y gutter, so the gap between two plots of the
+  /// row is the column gap.
   void set_right_gutter(f32 device_px) noexcept {
     right_gutter_ = device_px > 0.0f ? device_px : 0.0f;
   }
   f32 right_gutter() const noexcept { return right_gutter_; }
 
-  /// Whether the shared x axis is the figure's: every row reserves no x label strip
-  /// and one shared axis is drawn under the last row (the default), or every row
-  /// draws its own labels and the figure draws nothing extra.
+  /// Whether rows with the same columns as the row below hand it their x axis (the
+  /// default; a row with different columns keeps its own), or every row draws its own
+  /// labels and the figure draws nothing extra.
   void set_x_labels_only_on_bottom(bool on) noexcept { labels_bottom_only_ = on; }
   bool x_labels_only_on_bottom() const noexcept { return labels_bottom_only_; }
 

include/plot/render/renderer.hpp

@@ -238,12 +238,13 @@ class Renderer {
   /// exactly as a stand-alone plot is, and `draw(Plot&)` itself is unchanged for
   /// single-plot hosts.
 
-  /// The figure's one shared x axis is the **bottom row's own**, so it is drawn by
-  /// that row's normal path: when the figure says labels belong on the bottom only
-  /// (the default), the rows above reserve no x chrome and the bottom row stages its
-  /// own labels and title once, inside its own strip -- the rect
-  /// `FigureLayout::x_axis_strip` reads back. With that switched off, every row keeps
-  /// its own chrome and each draws its own labels; there is then no shared axis.
+  /// A shared x axis is the **bottom row's own** (of a run of rows with the same
+  /// columns), so it is drawn by that row's normal path: when the figure says labels
+  /// belong on the bottom only (the default), the rows above that match the row below
+  /// reserve no x chrome and the bottom row stages its own labels and title once,
+  /// inside its own strip -- the rect `FigureLayout::x_axis_strip` reads back. A row
+  /// whose columns differ keeps and draws its own; with that switched off, every row
+  /// does and there is no shared axis.
 
   /// Styling, the text backend and `ui_scale` are installed on **every** row before
   /// the figure computes its layout, so the strips the rows measure and the strokes