From 10b539ec271ce563e965b81c7c7d6b1e71497694 Mon Sep 17 00:00:00 2001
From: Andrew Duthie <andrew@andrewduthie.com>
Date: Thu, 25 Apr 2019 09:54:43 -0400
Subject: [PATCH] Documentation: Document withGlobalEvents

---
 packages/compose/README.md                      | 15 ++++++++++++++-
 .../compose/src/with-global-events/index.js     | 17 +++++++++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index 0540c0e2753e5..b7db41522461c 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -121,7 +121,20 @@ _Returns_
 
 <a name="withGlobalEvents" href="#withGlobalEvents">#</a> **withGlobalEvents**
 
-Undocumented declaration.
+Higher-order component creator which, given an object of DOM event types and
+values corresponding to a callback function name on the component, will
+create or update a window event handler to invoke the callback when an event
+occurs. On behalf of the consuming developer, the higher-order component
+manages unbinding when the component unmounts, and binding at most a single
+event handler for the entire application.
+
+_Parameters_
+
+-   _eventTypesToHandlers_ `Object<string,string>`: Object with keys of DOM event type, the value a name of the function on the original component's instance which handles the event.
+
+_Returns_
+
+-   `Function`: Higher-order component.
 
 <a name="withInstanceId" href="#withInstanceId">#</a> **withInstanceId**
 
diff --git a/packages/compose/src/with-global-events/index.js b/packages/compose/src/with-global-events/index.js
index f00f222a2d2be..bf32f27743232 100644
--- a/packages/compose/src/with-global-events/index.js
+++ b/packages/compose/src/with-global-events/index.js
@@ -21,6 +21,23 @@ import Listener from './listener';
  */
 const listener = new Listener();
 
+/**
+ * Higher-order component creator which, given an object of DOM event types and
+ * values corresponding to a callback function name on the component, will
+ * create or update a window event handler to invoke the callback when an event
+ * occurs. On behalf of the consuming developer, the higher-order component
+ * manages unbinding when the component unmounts, and binding at most a single
+ * event handler for the entire application.
+ *
+ * @param {Object<string,string>} eventTypesToHandlers Object with keys of DOM
+ *                                                     event type, the value a
+ *                                                     name of the function on
+ *                                                     the original component's
+ *                                                     instance which handles
+ *                                                     the event.
+ *
+ * @return {Function} Higher-order component.
+ */
 function withGlobalEvents( eventTypesToHandlers ) {
 	return createHigherOrderComponent( ( WrappedComponent ) => {
 		class Wrapper extends Component {