ui/app: expand package documentation

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

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

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