ui/paint: expand documentation and add package description

Signed-off-by: Elias Naur <mail@eliasnaur.com>

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

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)}
 }

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{