Update hashchange docs and tweak function names.

This is mostly doc updates, and we also rename
a couple functions to have more consistent naming.

docs/subsystems/hashchange-system.md

@@ -53,27 +53,27 @@ all of this (would be a good project to add them to the
 [Casper suite][testing-with-casper]) and there's enough complexity
 that it's easy to accidentally break something.
 
-Here's some notes on how we handle these cases:
+The main external API is below:
+
+* `hashchange.update_browser_history` is used to update the browser
+  history, and it should be called when the app code is taking care
+  of updating the UI directly
+* `hashchange.go_to_location` is used when you want the `hashchange`
+  module to actually dispatch building the next page
+
+Internally you have these functions:
 
 * `hashchange.hashchanged` is the function used to handle the hash,
-  when it's changed by the browser (e.g. by clicking on a link to
-  a hash or using the back button).
-* `hashchange.is_overlay_hash` is the function `hashchange.hashchanged`
-  calls to make it possible for clicking on links within a given
-  overlay to just be managed by code within that overlay, without
-  reloading the overlay.  It primarily checks whether the "main hash"
-  (i.e. the first piece like `settings` for `#settings/your-account`) is an overlay.
-* `hashchange.do_hashchange` is what is called when the user reloads the
-  browser.  If the hash is nonempty, it ensures the relevant overlay
-  is opened or the user is narrowed as part of the page load process.
-  It is also is called by `hashchange.hashchanged` when the hash
-  changes outside the `is_overlay_hash` boundaries, since the logic for
-  that case is identical.
-* `reload.preserve_state` is called when a server-initiated browser
-  reload happens, and encodes a bunch of data like the current scroll
-  position into the hash.
-* `reload.initialize` handles restoring the preserved state after a
-  reload where the hash starts with `/#reload`.
+  whether it's changed by the browser (e.g. by clicking on a link to
+  a hash or using the back button) or triggered internally.
+* `hashchange.do_hashchange_normal` handles most cases, like loading the main
+  page (but maybe with a specific URL if you are narrowed to a
+  stream or topic or PMs, etc.).
+* `hashchange.do_hashchange_overlay` handles overlay cases.  Overlays have
+  some minor complexity related to remembering the page from
+  which the overlay was launched, as well as optimizing in-page
+  transitions (i.e. don't close/re-open the overlay if you can
+  easily avoid it).
 
 ## Server-initiated reloads
 
@@ -103,6 +103,14 @@ reload itself:
   desynchronize when browsers start attempting them randomly, in
   order to avoid a thundering herd situation bringing down the server.
 
+Here are some key functions in the reload system:
+
+* `reload.preserve_state` is called when a server-initiated browser
+  reload happens, and encodes a bunch of data like the current scroll
+  position into the hash.
+* `reload.initialize` handles restoring the preserved state after a
+  reload where the hash starts with `/#reload`.
+
 ## All reloads
 
 In addition to saving state as described above when reloading the

static/js/hashchange.js

@@ -81,7 +81,7 @@ function activate_home_tab() {
 }
 
 // Returns true if this function performed a narrow
-function do_hashchange(from_reload) {
+function do_hashchange_normal(from_reload) {
     // If window.location.hash changed because our app explicitly
     // changed it, then we don't need to do anything.
     // (This function only neds to jump into action if it changed
@@ -194,7 +194,7 @@ function is_overlay_hash(hash) {
     return overlay_list.indexOf(main_hash) > -1;
 }
 
-function hashchanged_overlay(old_hash) {
+function do_hashchange_overlay(old_hash) {
     var base = get_main_hash(window.location.hash);
     var old_base = get_main_hash(old_hash);
 
@@ -284,14 +284,14 @@ function hashchanged(from_reload, e) {
     }
 
     if (is_overlay_hash(window.location.hash)) {
-        hashchanged_overlay(old_hash);
+        do_hashchange_overlay(old_hash);
         return;
     }
 
     // We are changing to a "main screen" view.
     overlays.close_for_hash_change();
     changing_hash = true;
-    var ret = do_hashchange(from_reload);
+    var ret = do_hashchange_normal(from_reload);
     changing_hash = false;
     return ret;
 }