From 87f8fd41527cfc8708d443e0decc6dd07f07e9a1 Mon Sep 17 00:00:00 2001
From: Elias Naur <mail@eliasnaur.com>
Date: Fri, 9 Aug 2019 21:17:33 +0200
Subject: [PATCH] ui/app: update documentation

Signed-off-by: Elias Naur <mail@eliasnaur.com>
---
 ui/app/app.go    | 12 +++++++++++-
 ui/app/window.go | 21 ++++++++++++++++-----
 2 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/ui/app/app.go b/ui/app/app.go
index eee8f64e..cc580c0d 100644
--- a/ui/app/app.go
+++ b/ui/app/app.go
@@ -17,7 +17,9 @@ import (
 // method must be called.
 type UpdateEvent struct {
 	Config Config
-	Size   image.Point
+	// Size is the dimensions of the window.
+	Size image.Point
+	// Insets is the insets to apply.
 	Insets Insets
 	// Whether this draw is system generated
 	// and needs a complete frame before
@@ -40,6 +42,8 @@ type Insets struct {
 	Top, Bottom, Left, Right ui.Value
 }
 
+// StageEvent is sent whenever the stage of a
+// Window changes.
 type StageEvent struct {
 	Stage Stage
 }
@@ -51,7 +55,10 @@ type CommandEvent struct {
 	Cancel bool
 }
 
+// Stage of a Window.
 type Stage uint8
+
+// CommandType is the type of a CommandEvent.
 type CommandType uint8
 
 type windowRendezvous struct {
@@ -66,7 +73,10 @@ type windowAndOptions struct {
 }
 
 const (
+	// StagePaused is the Stage for inactive Windows.
+	// Inactive Windows don't receive UpdateEvents.
 	StagePaused Stage = iota
+	// StateRunning is for active Windows.
 	StageRunning
 )
 
diff --git a/ui/app/window.go b/ui/app/window.go
index 5ec5c04e..f99a3af6 100644
--- a/ui/app/window.go
+++ b/ui/app/window.go
@@ -15,12 +15,15 @@ import (
 	"gioui.org/ui/system"
 )
 
+// WindowOptions specifies a set of window properties
+// for creating new Windows.
 type WindowOptions struct {
 	Width  ui.Value
 	Height ui.Value
 	Title  string
 }
 
+// Window represents an operating system window.
 type Window struct {
 	driver    *window
 	lastFrame time.Time
@@ -43,8 +46,8 @@ type Window struct {
 }
 
 // Queue is an input.Queue implementation that distributes
-// system input events to the input handlers declared through
-// Draw.
+// system input events to the input handlers declared in the
+// most recent call to Update.
 type Queue struct {
 	q iinput.Router
 }
@@ -72,7 +75,8 @@ var ackEvent input.Event
 // options. The options are hints; the platform is free to
 // ignore or adjust them.
 // If the current program is running on iOS and Android,
-// NewWindow returns the window previously by the platform.
+// NewWindow returns the window previously created by the
+// platform.
 func NewWindow(opts *WindowOptions) *Window {
 	if opts == nil {
 		opts = &WindowOptions{
@@ -96,14 +100,21 @@ func NewWindow(opts *WindowOptions) *Window {
 	return w
 }
 
+// Events returns the channel where events are delivered.
 func (w *Window) Events() <-chan input.Event {
 	return w.out
 }
 
+// Queue returns the Window's event queue. The queue contains
+// the events received since the last UpdateEvent.
 func (w *Window) Queue() *Queue {
 	return &w.queue
 }
 
+// Update updates the Window. Paint operations updates the
+// window contents, input operations declare input handlers,
+// and so on. The supplied operations list completely replaces
+// the window state from previous calls.
 func (w *Window) Update(frame *ui.Ops) {
 	w.frames <- frame
 }
@@ -139,8 +150,8 @@ func (w *Window) draw(size image.Point, frame *ui.Ops) {
 }
 
 // Invalidate the current window such that a UpdateEvent will be generated
-// immediately. If the window is not active, the redraw will trigger
-// when the window becomes active.
+// immediately. If the window is inactive, the event is sent when the
+// window becomes active.
 func (w *Window) Invalidate() {
 	select {
 	case w.invalidates <- struct{}{}: