all: improve documentation

Fixes #17

README.md

@@ -19,41 +19,53 @@ triggers the desired hotkey. A hotkey must be a combination of modifiers
 and a single key.
 
 ```go
+package main
+
 import (
-    "golang.design/x/hotkey"
-    "golang.design/x/hotkey/mainthread"
+	"log"
+
+	"golang.design/x/hotkey"
+	"golang.design/x/hotkey/mainthread"
 )
 
 func main() { mainthread.Init(fn) } // Not necessary when use in Fyne, Ebiten or Gio.
 func fn() {
-    hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}, hotkey.KeyS)
-    err := hk.Register()
-    if err != nil {
-        return
-    }
-    fmt.Printf("hotkey: %v is registered\n", hk)
-    <-hk.Keydown()
-    fmt.Printf("hotkey: %v is down\n", hk)
-    <-hk.Keyup()
-    fmt.Printf("hotkey: %v is up\n", hk)
-    hk.Unregister()
-    fmt.Printf("hotkey: %v is unregistered\n", hk)
+	hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}, hotkey.KeyS)
+	err := hk.Register()
+	if err != nil {
+		log.Fatalf("hotkey: failed to register hotkey: %v", err)
+		return
+	}
+
+	log.Printf("hotkey: %v is registered\n", hk)
+	<-hk.Keydown()
+	log.Printf("hotkey: %v is down\n", hk)
+	<-hk.Keyup()
+	log.Printf("hotkey: %v is up\n", hk)
+	hk.Unregister()
+	log.Printf("hotkey: %v is unregistered\n", hk)
 }
 ```
 
 Note platform specific details:
 
-- On macOS, due to the OS restriction (other
-  platforms does not have this restriction), hotkey events must be handled
-  on the "main thread". Therefore, in order to use this package properly,
-  one must start an OS main event loop on the main thread, For self-contained
-  applications, using [golang.design/x/hotkey/mainthread](https://pkg.go.dev/golang.design/x/hotkey/mainthread) is possible.
-  For applications based on other GUI frameworks, such as fyne, ebiten, or Gio.
-  This is not necessary. See the "[./examples](./examples)" folder for more examples.
+- On macOS, due to the OS restriction (other platforms does not have this
+  restriction), hotkey events must be handled on the "main thread".
+  Therefore, in order to use this package properly, one must start an OS
+  main event loop on the main thread, For self-contained applications,
+  using [golang.design/x/hotkey/mainthread](https://pkg.go.dev/golang.design/x/hotkey/mainthread)
+  is possible. It is uncessary or applications based on other GUI frameworks,
+  such as fyne, ebiten, or Gio. See the "[./examples](./examples)" folder
+  for more examples.
 - On Linux (X11), when AutoRepeat is enabled in the X server, the Keyup
   is triggered automatically and continuously as Keydown continues.
-- If this package did not include a desired key, one can always provide the keycode to the API.
-  For example, if a key code is 0x15, then the corresponding key is `hotkey.Key(0x15)`.
+- On Linux (X11), some keys may be mapped to multiple Mod keys. To
+  correctly register the key combination, one must use the correct
+  underlying keycode combination. For example, a regular Ctrl+Alt+S
+  might be registered as: Ctrl+Mod2+Mod4+S.
+- If this package did not include a desired key, one can always provide
+  the keycode to the API. For example, if a key code is 0x15, then the
+  corresponding key is `hotkey.Key(0x15)`.
 
 ## Examples
 
@@ -65,6 +77,7 @@ Note platform specific details:
 | A example to use in Fyne | [fyne](./examples/fyne/main.go) |
 | A example to use in Ebiten | [ebiten](./examples/ebiten/main.go) |
 | A example to use in Gio | [gio](./examples/gio/main.go) |
+
 ## Who is using this package?
 
 The main purpose of building this package is to support the

examples/minimum/main.go

@@ -1,28 +1,29 @@
 // Copyright 2022 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.
-
 package main
 
 import (
-	"fmt"
+	"log"
 
 	"golang.design/x/hotkey"
 	"golang.design/x/hotkey/mainthread"
 )
 
-func main() { mainthread.Init(fn) }
+func main() { mainthread.Init(fn) } // Not necessary when use in Fyne, Ebiten or Gio.
 func fn() {
 	hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}, hotkey.KeyS)
 	err := hk.Register()
 	if err != nil {
+		log.Fatalf("hotkey: failed to register hotkey: %v", err)
 		return
 	}
-	fmt.Printf("hotkey: %v is registered\n", hk)
+
+	log.Printf("hotkey: %v is registered\n", hk)
 	<-hk.Keydown()
-	fmt.Printf("hotkey: %v is down\n", hk)
+	log.Printf("hotkey: %v is down\n", hk)
 	<-hk.Keyup()
-	fmt.Printf("hotkey: %v is up\n", hk)
+	log.Printf("hotkey: %v is up\n", hk)
 	hk.Unregister()
-	fmt.Printf("hotkey: %v is unregistered\n", hk)
+	log.Printf("hotkey: %v is unregistered\n", hk)
 }

hotkey.go

@@ -11,32 +11,54 @@
 //
 // Note platform specific details:
 //
-// - On "macOS" due to the OS restriction (other
-//   platforms does not have this restriction), hotkey events must be handled
-//   on the "main thread". Therefore, in order to use this package properly,
-//   one must start an OS main event loop on the main thread, For self-contained
-//   applications, using golang.design/x/hotkey/mainthread is possible.
-//   For applications based on other GUI frameworks, such as fyne, ebiten, or Gio.
-//   This is not necessary. See the "./examples" folder for more examples.
+//   - On macOS, due to the OS restriction (other platforms does not have
+//     this restriction), hotkey events must be handled on the "main thread".
+//     Therefore, in order to use this package properly, one must start an
+//     OS main event loop on the main thread, For self-contained applications,
+//     using [golang.design/x/hotkey/mainthread](https://pkg.go.dev/golang.design/x/hotkey/mainthread)
+//     is possible. It is uncessary or applications based on other GUI frameworks,
+//     such as fyne, ebiten, or Gio. See the "[./examples](./examples)" folder
+//     for more examples.
 //
-// - On Linux (X11), When AutoRepeat is enabled in the X server, the Keyup
-//   is triggered automatically and continuously as Keydown continues.
+//   - On Linux (X11), when AutoRepeat is enabled in the X server, the
+//     Keyup is triggered automatically and continuously as Keydown continues.
 //
-// 	func main() { mainthread.Init(fn) } // not necessary when use in Fyne, Ebiten or Gio.
-// 	func fn() {
-// 		hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}, hotkey.KeyS)
-// 		err := hk.Register()
-// 		if err != nil {
-// 			return
-// 		}
-// 		fmt.Printf("hotkey: %v is registered\n", hk)
-// 		<-hk.Keydown()
-// 		fmt.Printf("hotkey: %v is down\n", hk)
-// 		<-hk.Keyup()
-// 		fmt.Printf("hotkey: %v is up\n", hk)
-// 		hk.Unregister()
-// 		fmt.Printf("hotkey: %v is unregistered\n", hk)
-// 	}
+//   - On Linux (X11), some keys may be mapped to multiple Mod keys. To
+//     correctly register the key combination, one must use the correct
+//     underlying keycode combination. For example, a regular Ctrl+Alt+S
+//     might be registered as: Ctrl+Mod2+Mod4+S.
+//
+//   - If this package did not include a desired key, one can always provide
+//     the keycode to the API. For example, if a key code is 0x15, then the
+//     corresponding key is `hotkey.Key(0x15)`.
+//
+// THe following is a minimum example:
+//
+//	package main
+//
+//	import (
+//		"log"
+//
+//		"golang.design/x/hotkey"
+//		"golang.design/x/hotkey/mainthread"
+//	)
+//
+//	func main() { mainthread.Init(fn) } // Not necessary when use in Fyne, Ebiten or Gio.
+//	func fn() {
+//		hk := hotkey.New([]hotkey.Modifier{hotkey.ModCtrl, hotkey.ModShift}, hotkey.KeyS)
+//		err := hk.Register()
+//		if err != nil {
+//			log.Fatalf("hotkey: failed to register hotkey: %v", err)
+//		}
+//
+//		log.Printf("hotkey: %v is registered\n", hk)
+//		<-hk.Keydown()
+//		log.Printf("hotkey: %v is down\n", hk)
+//		<-hk.Keyup()
+//		log.Printf("hotkey: %v is up\n", hk)
+//		hk.Unregister()
+//		log.Printf("hotkey: %v is unregistered\n", hk)
+//	}
 package hotkey
 
 import (