docs: Mention the limitation of globalShortcut

Close #3816.

diff --git a/docs/api/global-shortcut.md b/docs/api/global-shortcut.md
index ab6123b..1ec0503 100644 (file)
--- a/docs/api/global-shortcut.md
+++ b/docs/api/global-shortcut.md
@@ -1,6 +1,6 @@
-# global-shortcut
+# globalShortcut
 
-The `global-shortcut` module can register/unregister a global keyboard shortcut
+The `globalShortcut` module can register/unregister a global keyboard shortcut
 with the operating system so that you can customize the operations for various
 shortcuts.
 
@@ -38,7 +38,7 @@ app.on('will-quit', function() {
 
 ## Methods
 
-The `global-shortcut` module has the following methods:
+The `globalShortcut` module has the following methods:
 
 ### `globalShortcut.register(accelerator, callback)`
 
@@ -46,17 +46,21 @@ The `global-shortcut` module has the following methods:
 * `callback` Function
 
 Registers a global shortcut of `accelerator`. The `callback` is called when
-the registered shortcut is pressed by the user. Returns `true` if the shortcut
-`accelerator` was registered, `false` otherwise. For example, the specified
-`accelerator` has already been registered by another caller or other native
-applications.
+the registered shortcut is pressed by the user.
+
+When the accelerator is already taken by other applications, this call will
+silently fail. This behavior is intended by operating systems, since they don't
+want applications to fight for global shortcuts.
 
 ### `globalShortcut.isRegistered(accelerator)`
 
 * `accelerator` [Accelerator](accelerator.md)
 
-Returns `true` or `false` depending on whether the shortcut `accelerator` is
-registered.
+Returns whether this application has registered `accelerator`.
+
+When the accelerator is already taken by other applications, this call will
+still return `false`. This behavior is intended by operating systems, since they
+don't want applications to fight for global shortcuts.
 
 ### `globalShortcut.unregister(accelerator)`