Add code comments for explicit file changes

Author: rgladwell

src/core/router/history/hash.js

@@ -18,6 +18,11 @@ export class HashHistory extends History {
     const path = window.location.pathname || '';
     const base = this.config.basePath;
 
+    // This handles the case where Docsify is served off an
+    // explicit file path, i.e.`/base/index.html#/blah`. This
+    // prevents the `/index.html` part of the URI from being
+    // remove during routing.
+    // See here: https://github.com/docsifyjs/docsify/pull/1372
     const basePath = path.endsWith('.html')
       ? path + '#/' + base
       : path + '/' + base;

src/core/router/util.js

@@ -76,6 +76,29 @@ export const resolvePath = cached(path => {
   return '/' + resolved.join('/');
 });
 
+/**
+ * Normalises the URI path to handle the case where Docsify is
+ * hosted off explicit files, i.e. /index.html. This function
+ * eliminates any path segments that contain `#` fragments.
+ *
+ * This is used to map browser URIs to markdown file sources.
+ *
+ * For example:
+ *
+ * http://example.org/base/index.html#/blah
+ *
+ * would be mapped to:
+ *
+ * http://example.org/base/blah.md.
+ *
+ * See here for more information:
+ *
+ * https://github.com/docsifyjs/docsify/pull/1372
+ *
+ * @param {string} path The URI path to normalise
+ * @return {string} { path, query }
+ */
+
 function normaliseFragment(path) {
   return path
     .split('/')