From a8f42cd567a4703aed100e89e348685ea3bee1de Mon Sep 17 00:00:00 2001
From: Elias Naur <mail@eliasnaur.com>
Date: Fri, 9 Aug 2019 22:16:52 +0200
Subject: [PATCH] ui/app: expand package documentation

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

diff --git a/ui/app/app.go b/ui/app/app.go
index c159a117..f4066c54 100644
--- a/ui/app/app.go
+++ b/ui/app/app.go
@@ -134,10 +134,12 @@ func DataDir() (string, error) {
 	return dataDir()
 }
 
-// Main must be called from the a program's main function.
+// Main must be called from the a program's main function. It
+// blocks until there are no more windows active.
+//
 // Calling Main is necessary because some operating systems
 // require control of the main thread of the program for
-// running user interfaces.
+// running windows.
 func Main() {
 	main()
 }
diff --git a/ui/app/doc.go b/ui/app/doc.go
index f7a9b4ec..84229aa2 100644
--- a/ui/app/doc.go
+++ b/ui/app/doc.go
@@ -4,5 +4,56 @@
 Package app provides a platform-independent interface to operating system
 functionality for running graphical user interfaces.
 
+Windows
+
+Create a new Window by callingNewWindow. On mobile platforms or when Gio
+is embedded in another project, NewWindow merely connects with a previously
+created window.
+
+A Window is run by receiving events from its Events channel. The most
+important event is UpdateEvent that prompts an update of the window
+contents and state.
+
+For example:
+
+	import "gioui.org/ui"
+
+	w := app.NewWindow(nil)
+	for e := range w.Events() {
+		if e, ok := e.(app.UpdateEvent); ok {
+			ops.Reset()
+			// Add operations to ops.
+			...
+			// Completely replace the window contents and state.
+			w.Update(ops)
+		}
+	}
+
+A program must keep receiving events from the event channel until
+DestroyEvent is received.
+
+Main
+
+The Main function must be called from a programs main function, to hand over
+control of the main thread to operating systems that need it.
+
+Because Main is also blocking, the event loop of a Window must run in a goroutine.
+
+For example, to display a blank but otherwise functional window:
+
+	package main
+
+	import "gioui.org/ui/app"
+
+	func main() {
+		go func() {
+			w := app.NewWindow(nil)
+			for range w.Events() {
+			}
+		}()
+		app.Main()
+	}
+
+
 */
 package app