From 8f37a565b9520441b077f68d61cb12bc0aa4239c Mon Sep 17 00:00:00 2001
From: Elias Naur <mail@eliasnaur.com>
Date: Sat, 10 Aug 2019 17:09:35 +0200
Subject: [PATCH] ui/layout: document layout types and helpers

Signed-off-by: Elias Naur <mail@eliasnaur.com>
---
 ui/layout/layout.go | 35 ++++++++++++++++++++++++-----------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/ui/layout/layout.go b/ui/layout/layout.go
index fb88b0cd..8e54a3d7 100644
--- a/ui/layout/layout.go
+++ b/ui/layout/layout.go
@@ -21,13 +21,22 @@ type Constraint struct {
 	Min, Max int
 }
 
+// Dimens are the resolved size and baseline for a user
+// interface element.
 type Dimens struct {
 	Size     image.Point
 	Baseline int
 }
 
+// Axis is the the Horizontal or Vertical direction.
 type Axis uint8
+
+// Alignment is the relative alignment of a list of
+// interface elements.
 type Alignment uint8
+
+// Direction is the alignment of a set of interface elements
+// relative to a containing space.
 type Direction uint8
 
 const (
@@ -54,6 +63,7 @@ const (
 	Vertical
 )
 
+// Constrain a value to the range [Min; Max].
 func (c Constraint) Constrain(v int) int {
 	if v < c.Min {
 		return c.Min
@@ -63,8 +73,9 @@ func (c Constraint) Constrain(v int) int {
 	return v
 }
 
-func (c Constraints) Constrain(p image.Point) image.Point {
-	return image.Point{X: c.Width.Constrain(p.X), Y: c.Height.Constrain(p.Y)}
+// Constrain a size to the Width and Height ranges.
+func (c Constraints) Constrain(size image.Point) image.Point {
+	return image.Point{X: c.Width.Constrain(size.X), Y: c.Height.Constrain(size.Y)}
 }
 
 // RigidConstraints returns the constraints that can only be
@@ -76,6 +87,7 @@ func RigidConstraints(size image.Point) Constraints {
 	}
 }
 
+// Inset adds space around an interface element.
 type Inset struct {
 	Top, Right, Bottom, Left ui.Value
 
@@ -85,6 +97,16 @@ type Inset struct {
 	cs                       Constraints
 }
 
+// Align aligns an interface element in the available space.
+type Align struct {
+	Alignment Direction
+
+	macro ui.MacroOp
+	ops   *ui.Ops
+	begun bool
+	cs    Constraints
+}
+
 func (in *Inset) Begin(c ui.Config, ops *ui.Ops, cs Constraints) Constraints {
 	if in.begun {
 		panic("must End before Begin")
@@ -135,15 +157,6 @@ func UniformInset(v ui.Value) Inset {
 	return Inset{Top: v, Right: v, Bottom: v, Left: v}
 }
 
-type Align struct {
-	Alignment Direction
-
-	macro ui.MacroOp
-	ops   *ui.Ops
-	begun bool
-	cs    Constraints
-}
-
 func (a *Align) Begin(ops *ui.Ops, cs Constraints) Constraints {
 	if a.begun {
 		panic("must End before Begin")