Document layout protocol

gui.rkt

@@ -107,18 +107,69 @@
   (i:rectangle w h "solid" (theme-button-background-color)))
 
 ;;---------------------------------------------------------------------------
+;; Protocol: Layout.
+;;---------------------------------------------------------------------------
+;; Roles:
+;;
+;;  Layout Solver
+;;    Responds to assertions of interest in layout solutions by
+;;    computing layouts and asserting the resulting positions.
+;;
+;;      (Observe LayoutSolution)+ ==>
+;;        RequestedLayoutSize ==>
+;;          ComputedLayoutSize ∧ LayoutSolution+
+;;
+;;  Layout Observer
+;;    Supplies any initial constraints on the overall layout size,
+;;    and may observe the final overall computed layout size.
+;;
+;;      RequestedLayoutSize ∧ (ComputedLayoutSize ==> 1)?
+;;
+;;  Layout Participant
+;;    Supplies constraints on an individual item to be laid out
+;;    and monitors the resulting position decision for that item.
+;;
+;;      LayoutSolution ==> 1
+;;---------------------------------------------------------------------------
 
+;; A LayoutSpec is one of
+;;  - (horizontal-layout Any)
+;;  - (vertical-layout Any)
+;;  - (tabular-layout Nat Nat)
+;; where the first two use their keys for *ordering* peers relative to
+;; each other using datum-order, and the last uses the given row and
+;; column to place the item within an implicitly-sized grid layout.
 (struct horizontal-layout (key) #:transparent)
 (struct vertical-layout (key) #:transparent)
 (struct tabular-layout (row col) #:transparent)
 
+;; ASSERTION. A RequestedLayoutSize is a
+;; (requested-layout-size Any (Option (box-size (Option Sizing) (Option Sizing))))
+;; and describes overall constraints on the total size of the layout to be
+;; constructed. Supplying `size` as `#f` means that there is no constraint at all;
+;; otherwise, the `box-size` given is used as the exact dimensions of
+;; the layout, unless one or both of the dimensions of the `box-size`
+;; are given as `#f`, in which case there is no constraint for that
+;; dimension.
 (struct requested-layout-size (container-id size) #:transparent)
+
+;; ASSERTION. A ComputedLayoutSize is a
+;; (computed-layout-size Any BoxSize)
+;; and gives the concrete dimensions of the layout after layout
+;; computation has completed.
 (struct computed-layout-size (container-id size) #:transparent)
+
+;; ASSERTION. A LayoutSolution is a
+;; (layout-solution Any LayoutSpec BoxSize Rectangle)
+;; and denotes the computed bounds of a given item within a layout.
+;; TODO: introduce an item ID??
 (struct layout-solution (container-id
                          spec
                          size
                          rectangle) #:transparent)
 
+;;---------------------------------------------------------------------------
+
 (struct layout-item (spec size) #:transparent)
 
 (define (layout-item-spec-key li)