all: update docs

Author: changkun

README.md

@@ -13,22 +13,35 @@ import "golang.design/x/mainthread"
 
 ## API Usage
 
+Package mainthread offers facilities to schedule functions on the
+maint hread. To use this package properly, one must call
+mainthread.Init from the main package. For example:
+
 ```go
 package main
 
 import "golang.design/x/mainthread"
 
-func main() {
-    mainthread.Init(fn)
-}
+func main() { mainthread.Init(fn) }
 
+// fn is the actual main function 
 func fn() {
-    mainthread.Call(func() {
-        // ... runs on the main thread ...
-    })
+    // mainthread.Call returns when f1 returns. Note that if f1 blocks
+    // it will also block the execution of any subsequent calls on the
+    // main thread.
+    mainthread.Call(f1)
+
+    // ... do whatever you want to do ...
 
-    // ... do what ever you want to do ...
+    // mainthread.Go returns immediately and f2 is scheduled to be executed
+    // in the future.
+    mainthread.Go(f2)
+
+    // ... do whatever you want to do ...
 }
+
+func f1() { ... }
+func f2() { ... }
 ```
 
 ## When do you need this package?

bench_test.go

@@ -0,0 +1,24 @@
+// Copyright 2020-2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+package mainthread_test
+
+import (
+	"testing"
+
+	"golang.design/x/mainthread"
+)
+
+func BenchmarkCall(b *testing.B) {
+	f := func() {}
+	mainthread.Init(func() {
+		b.ReportAllocs()
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			mainthread.Call(f)
+		}
+	})
+}

example_test.go

@@ -0,0 +1,40 @@
+// Copyright 2020-2021 The golang.design Initiative Authors.
+// All rights reserved. Use of this source code is governed
+// by a MIT license that can be found in the LICENSE file.
+//
+// Written by Changkun Ou <changkun.de>
+
+package mainthread_test
+
+import (
+	"fmt"
+
+	"golang.design/x/mainthread"
+)
+
+func ExampleInit() {
+	mainthread.Init(func() {
+		// ... Do stuff ...
+	})
+	// Output:
+}
+
+func ExampleCall() {
+	mainthread.Init(func() {
+		mainthread.Call(func() {
+			fmt.Println("from main thread")
+		})
+	})
+	// Output: from main thread
+}
+
+func ExampleGo() {
+	mainthread.Init(func() {
+		done := make(chan string)
+		mainthread.Go(func() {
+			done <- "main thread"
+		})
+		fmt.Println("from", <-done)
+	})
+	// Output: from main thread
+}

mainthread.go

@@ -1,9 +1,37 @@
-// Copyright 2021 The golang.design Initiative Authors.
+// Copyright 2020-2021 The golang.design Initiative Authors.
 // All rights reserved. Use of this source code is governed
 // by a MIT license that can be found in the LICENSE file.
 //
 // Written by Changkun Ou <changkun.de>
 
+// Package mainthread offers facilities to schedule functions on the
+// maint hread. To use this package properly, one must call
+// mainthread.Init from the main package. For example:
+//
+// 	package main
+//
+// 	import "golang.design/x/mainthread"
+//
+// 	func main() { mainthread.Init(fn) }
+//
+// 	// fn is the actual main function
+// 	func fn() {
+// 		// mainthread.Call returns when f1 returns. Note that if f1
+// 		// blocks it will also block the execution of any subsequent
+// 		// calls on the main thread.
+// 		mainthread.Call(f1)
+//
+// 		// ... do whatever you want to do ...
+//
+// 		// mainthread.Go returns immediately and f2 is scheduled to be
+// 		// executed in the future.
+// 		mainthread.Go(f2)
+//
+// 		// ... do whatever you want to do ...
+// 	}
+//
+// 	func f1() { ... }
+// 	func f2() { ... }
 package mainthread // import "golang.design/x/mainthread"
 
 import (

mainthread_test.go

@@ -1,4 +1,4 @@
-// Copyright 2021 The golang.design Initiative Authors.
+// Copyright 2020-2021 The golang.design Initiative Authors.
 // All rights reserved. Use of this source code is governed
 // by a MIT license that can be found in the LICENSE file.
 //
@@ -11,7 +11,6 @@ package mainthread_test
 
 import (
 	"context"
-	"fmt"
 	"os"
 	"sync"
 	"sync/atomic"
@@ -85,31 +84,11 @@ func TestGo(t *testing.T) {
 		t.Fatalf("mainthread.Go is not executing in parallel")
 	}
 
-	ctxx, cancell := context.WithTimeout(context.Background(), time.Second)
+	ctxx, cancell := context.WithTimeout(context.Background(), time.Second*2)
 	defer cancell()
 	select {
 	case <-ctxx.Done():
 		t.Fatalf("mainthread.Go never schedules the function")
 	case <-done:
 	}
 }
-
-func BenchmarkCall(b *testing.B) {
-	f := func() {}
-	mainthread.Init(func() {
-		b.ReportAllocs()
-		b.ResetTimer()
-		for i := 0; i < b.N; i++ {
-			mainthread.Call(f)
-		}
-	})
-}
-
-func ExampleInit() {
-	mainthread.Init(func() {
-		mainthread.Call(func() {
-			fmt.Println("from main thread")
-		})
-	})
-	// Output: from main thread
-}