Add comments to gear_menu.js.

static/js/gear_menu.js

@@ -2,6 +2,76 @@ var gear_menu = (function () {
 
 var exports = {};
 
+/*
+For various historical reasons there isn't one
+single chunk of code that really makes our gear
+menu function.  In this comment I try to help
+you know where to look for relevant code.
+
+The module that you're reading now doesn't
+actually doesn't do much of the work.
+
+Our gear menu has these choices:
+
+=================
+hash:  Manage streams
+hash:  Settings
+hash:  Organization settings
+---
+link:  Help center
+info:  Keyboard shortcuts
+info:  Message formatting
+info:  Search operators
+---
+link:  Desktop & mobile apps
+link:  Integrations
+link:  API documentation
+link:  Statistics
+---
+hash:   Invite users
+---
+misc:  Logout
+=================
+
+Depending on settings, there may also be choices
+like "Feedback" or "Debug".
+
+The menu items get built in a server-side template called
+templates/zerver/app/navbar.html.  Each item is
+an HTML anchor tag with a "role" of "menuitem".
+
+The menu itself has the selector
+"settings-dropdown".
+
+The items with the prefix of "hash:" are in-page
+links:
+
+    #streams
+    #settings
+    #organization
+    #invite
+
+When you click on the links there is a function
+called hashchanged() in static/js/hashchange.js
+that gets invoked.  (We use window.onhashchange
+to register the handler.)  This function then
+launches the appropriate modal for each menu item.
+Look for things like subs.launch(...) or
+invite.launch() in that code.
+
+Some items above are prefixed with "link:".  Those
+items, when clicked, just use the normal browser
+mechanism to link to external pages, and they
+have a target of "_blank".
+
+The "info:" items use our info overlay system
+in static/js/info_overlay.js.  They are dispatched
+using a click handler in static/js/click_handlers.js.
+The click handler uses "[data-overlay-trigger]" as
+the selector and then calls info_overlay.show.
+
+*/
+
 // We want to remember how far we were scrolled on each 'tab'.
 // To do so, we need to save away the old position of the
 // scrollbar when we switch to a new tab (and restore it