From b25af47c45adcaef27ae241623f40208c53a1866 Mon Sep 17 00:00:00 2001
From: Elias Naur <mail@eliasnaur.com>
Date: Sun, 11 Aug 2019 18:39:46 +0200
Subject: [PATCH] ui/paint: expand documentation and add package description

Signed-off-by: Elias Naur <mail@eliasnaur.com>
---
 ui/paint/doc.go   | 15 +++++++++++++++
 ui/paint/paint.go | 13 ++++++++++---
 ui/paint/path.go  | 12 ++++++++++--
 3 files changed, 35 insertions(+), 5 deletions(-)
 create mode 100644 ui/paint/doc.go

diff --git a/ui/paint/doc.go b/ui/paint/doc.go
new file mode 100644
index 00000000..eeb15497
--- /dev/null
+++ b/ui/paint/doc.go
@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Unlicense OR MIT
+
+/*
+Package paint provides operations for 2D graphics.
+
+The PaintOp operation draws the current material into a rectangular
+area, taking the current clip path and transformation into account.
+
+The material is set by either a ColorOp for a constant color, or
+ImageOp for an image.
+
+The ClipOp operation sets the clip path. Drawing outside the clip
+path is ignored. A path is a closed shape of lines or curves.
+*/
+package paint
diff --git a/ui/paint/paint.go b/ui/paint/paint.go
index 1306466b..e7cd6cd5 100644
--- a/ui/paint/paint.go
+++ b/ui/paint/paint.go
@@ -13,15 +13,22 @@ import (
 	"gioui.org/ui/internal/opconst"
 )
 
+// ImageOp sets the material to a section of an
+// image.
 type ImageOp struct {
-	Src  image.Image
+	// Src is the image.
+	Src image.Image
+	// Rect defines the section of Src to use.
 	Rect image.Rectangle
 }
 
+// ColorOp sets the material to a constant color.
 type ColorOp struct {
 	Color color.RGBA
 }
 
+// PaintOp draws the current material, respecting the
+// clip path and transformation.
 type PaintOp struct {
 	Rect f32.Rectangle
 }
@@ -58,8 +65,8 @@ func (d PaintOp) Add(o *ui.Ops) {
 	o.Write(data)
 }
 
-// RectClip returns a ClipOp op corresponding to
-// a pixel aligned rectangular area.
+// RectClip returns a ClipOp corresponding to a pixel aligned
+// rectangular area.
 func RectClip(r image.Rectangle) ClipOp {
 	return ClipOp{bounds: toRectF(r)}
 }
diff --git a/ui/paint/path.go b/ui/paint/path.go
index 877b97e1..029a3829 100644
--- a/ui/paint/path.go
+++ b/ui/paint/path.go
@@ -13,6 +13,11 @@ import (
 	"gioui.org/ui/internal/path"
 )
 
+// PathBuilder builds and adds a general ClipOp clip path
+// from lines and curves.
+// PathBuilder generates no garbage and can be used for
+// dynamic paths; path data is stored directly in the Ops
+// list supplied to Init.
 type PathBuilder struct {
 	ops       *ui.Ops
 	firstVert int
@@ -23,8 +28,7 @@ type PathBuilder struct {
 	hasBounds bool
 }
 
-// ClipOp structure must match opClip in package ui/internal/gpu.
-
+// ClipOp sets the current clip path.
 type ClipOp struct {
 	bounds f32.Rectangle
 }
@@ -40,6 +44,8 @@ func (p ClipOp) Add(o *ui.Ops) {
 	o.Write(data)
 }
 
+// Init the builder and specify the operations list for
+// storing the path data and final ClipOp.
 func (p *PathBuilder) Init(ops *ui.Ops) {
 	p.ops = ops
 }
@@ -276,6 +282,8 @@ func (p *PathBuilder) simpleQuadTo(ctrl, to f32.Point) {
 	p.pen = to
 }
 
+// End the path and add the resulting ClipOp to
+// the operation list passed to Init.
 func (p *PathBuilder) End() {
 	p.end()
 	ClipOp{