From a2baffdbfd94ebe3194264524c40f3a986d0af4b Mon Sep 17 00:00:00 2001
From: Elias Naur <mail@eliasnaur.com>
Date: Fri, 9 Aug 2019 20:32:39 +0200
Subject: [PATCH] ui: expand package documentation

Signed-off-by: Elias Naur <mail@eliasnaur.com>
---
 ui/doc.go | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 ui/ops.go |  7 ++++-
 ui/ui.go  |  6 ++---
 3 files changed, 87 insertions(+), 7 deletions(-)

diff --git a/ui/doc.go b/ui/doc.go
index 1042c623..5d9a1aa2 100644
--- a/ui/doc.go
+++ b/ui/doc.go
@@ -1,9 +1,84 @@
+// SPDX-License-Identifier: Unlicense OR MIT
+
 /*
+Package ui defines operations buffers, units and common operations
+for GUI programs written with the Gio module.
 
-Package ui implements portable desktop and mobile GUI programs.
+See https://gioui.org for instructions to setup and run Gio programs.
 
-See https://gioui.org for instructions to setup dependencies and
-run Gio programs.
+Operations
 
+Gio programs use operations, or ops, for describing their user
+interfaces. There are operations for drawing, defining input
+handlers, changing window properties as well as operations for
+controlling the execution of other operations.
+
+Ops represents a list of operations. The most important use
+for an Ops list is to describe a complete user interface update
+to a ui/app.Window's Update method.
+
+Drawing a colored square:
+
+	import "gioui.org/ui"
+	import "gioui.org/ui/app"
+	import "gioui.org/ui/paint"
+
+	var w app.Window
+	var ops ui.Ops
+	...
+	ops.Reset()
+	paint.ColorOp{Color: ...}.Add(ops)
+	paint.PaintOp{Rect: ...}.Add(ops)
+	w.Update(ops)
+
+State
+
+An Ops list can be viewed as a very simple virtual machine: it has an implicit
+mutable state stack and execution flow can be controlled with macros.
+
+The StackOp saves the current state to the state stack and restores it later:
+
+	var ops ui.Ops
+	var stack ui.StackOp
+	// Save the current state, in particular the transform.
+	stack.Push(ops)
+	// Apply a transform to subsequent operations.
+	ui.TransformOp{}.Offset(...).Add(ops)
+	...
+	// Restore the previous transform.
+	stack.Pop()
+
+The MacroOp records a list of operations to be executed later:
+
+	var ops ui.Ops
+	var macro ui.MacroOp
+	macro.Record()
+	// Record operations by adding them.
+	ui.InvalidateOp{}.Add(ops)
+	...
+	macro.Stop()
+	...
+	// Execute the recorded operations.
+	macro.Add(ops)
+
+Note that operations added between Record and Stop are not executed until
+the macro is Added.
+
+Units
+
+A Value is a value with a Unit attached.
+
+Device independent pixel, or dp, is the unit for sizes independent of
+the underlying display device.
+
+Scaled pixels, or sp, is the unit for text sizes. An sp is like dp with
+text scaling applied.
+
+Finally, pixels, or px, is the unit for display dependent pixels. Their
+size vary between platforms and displays.
+
+To maintain a constant visual size across platforms and displays, always
+use dps or sps to define user interfaces. Only use pixels for derived
+values.
 */
 package ui
diff --git a/ui/ops.go b/ui/ops.go
index 46cfe3aa..f4a22891 100644
--- a/ui/ops.go
+++ b/ui/ops.go
@@ -8,7 +8,9 @@ import (
 	"gioui.org/ui/internal/opconst"
 )
 
-// Ops holds a list of serialized operations.
+// Ops holds a list of operations. Operations are stored in
+// serialized form to avoid garbage during construction of
+// the ops list.
 type Ops struct {
 	// version is incremented at each Reset.
 	version int
@@ -176,6 +178,9 @@ func (m *MacroOp) Stop() {
 	m.version = m.ops.version
 }
 
+// Add the recorded list of operations. The Ops
+// argument may be different than the Ops argument
+// passed to Record.
 func (m MacroOp) Add(o *Ops) {
 	if m.recording {
 		panic("a recording is in progress")
diff --git a/ui/ui.go b/ui/ui.go
index 3b604806..16e2f115 100644
--- a/ui/ui.go
+++ b/ui/ui.go
@@ -11,8 +11,8 @@ import (
 	"gioui.org/ui/internal/opconst"
 )
 
-// Config represents the essential configuration for
-// updating and drawing a user interface.
+// Config define the essential properties of
+// the environment.
 type Config interface {
 	// Now returns the current animation time.
 	Now() time.Time
@@ -26,7 +26,7 @@ type InvalidateOp struct {
 	At time.Time
 }
 
-// TransformOp applies a transform to later ops.
+// TransformOp applies a transform to the current transform.
 type TransformOp struct {
 	// TODO: general transformations.
 	offset f32.Point