Merge pull request #408 from documentationjs/file-order

Sort documentation in code order.

Author: tmcw

lib/git/url_prefix.js

@@ -16,7 +16,22 @@ function getGithubURLPrefix(root) {
     var head = fs.readFileSync(path.join(root, '.git', 'HEAD'), 'utf8');
     var branch = head.match(/ref\: (.*)/);
     if (branch) {
-      var sha = fs.readFileSync(path.join(root, '.git', branch[1]), 'utf8');
+      var branchFileName = path.join(root, '.git', branch[1]);
+      var packedRefsName = path.join(root, '.git', 'packed-refs');
+      var sha;
+      if (fs.existsSync(branchFileName)) {
+        sha = fs.readFileSync(branchFileName, 'utf8');
+      } else if (fs.existsSync(packedRefsName)) {
+        sha = fs.readFileSync(packedRefsName, 'utf8')
+          .split(/\n/)
+          .filter(function (line) {
+            return line[0] !== '#' && line[0] !== '^';
+          })
+          .reduce(function (memo, line) {
+            memo[line.split(' ')[1]] = line.split(' ')[0];
+            return memo;
+          }, {})[branch[1]];
+      }
     } else {
       sha = head;
     }

lib/sort.js

@@ -11,7 +11,7 @@
  * @private
  */
 function getSortKey(comment, order) {
-  var key = comment.name || comment.context.file;
+  var key = comment.context.file + ':' + comment.context.loc.start.line || comment.name;
 
   if (order && order.indexOf(key) !== -1) {
     return order.indexOf(key);

package.json

@@ -56,7 +56,6 @@
     "eslint": "^2.0.0",
     "fs-extra": "^0.26.2",
     "glob": "^7.0.0",
-    "lodash": "^4.3.0",
     "mock-fs": "^3.5.0",
     "tap": "^5.4.4",
     "tmp": "0.0.28",

test/fixture/_external-deps-included.json

@@ -176,7 +176,7 @@
     },
     "tags": [
       {
-        "title": "return",
+        "title": "returns",
         "description": "numberone",
         "lineNumber": 2,
         "type": {
@@ -187,26 +187,26 @@
     ],
     "loc": {
       "start": {
-        "line": 1,
+        "line": 5,
         "column": 0
       },
       "end": {
-        "line": 4,
+        "line": 8,
         "column": 3
       }
     },
     "context": {
       "loc": {
         "start": {
-          "line": 5,
+          "line": 9,
           "column": 0
         },
         "end": {
-          "line": 8,
+          "line": 12,
           "column": 2
         }
       },
-      "code": "/**\n * This function returns the number one.\n * @return {Number} numberone\n */\nmodule.exports = function () {\n  // this returns 1\n  return 1;\n};\n"
+      "code": "'use strict';\n\nvar otherDep = require('external2');\n\n/**\n * This function returns the number one.\n * @returns {Number} numberone\n */\nmodule.exports = function () {\n  // this returns 1\n  return otherDep() - 1;\n};\n"
     },
     "errors": [],
     "returns": [
@@ -269,14 +269,14 @@
         }
       }
     ],
-    "name": "index",
+    "name": "main",
     "kind": "function",
     "members": {
       "instance": [],
       "static": []
     },
     "path": [
-      "index"
+      "main"
     ]
   },
   {
@@ -334,7 +334,7 @@
     },
     "tags": [
       {
-        "title": "returns",
+        "title": "return",
         "description": "numberone",
         "lineNumber": 2,
         "type": {
@@ -345,26 +345,26 @@
     ],
     "loc": {
       "start": {
-        "line": 5,
+        "line": 1,
         "column": 0
       },
       "end": {
-        "line": 8,
+        "line": 4,
         "column": 3
       }
     },
     "context": {
       "loc": {
         "start": {
-          "line": 9,
+          "line": 5,
           "column": 0
         },
         "end": {
-          "line": 12,
+          "line": 8,
           "column": 2
         }
       },
-      "code": "'use strict';\n\nvar otherDep = require('external2');\n\n/**\n * This function returns the number one.\n * @returns {Number} numberone\n */\nmodule.exports = function () {\n  // this returns 1\n  return otherDep() - 1;\n};\n"
+      "code": "/**\n * This function returns the number one.\n * @return {Number} numberone\n */\nmodule.exports = function () {\n  // this returns 1\n  return 1;\n};\n"
     },
     "errors": [],
     "returns": [
@@ -427,14 +427,14 @@
         }
       }
     ],
-    "name": "main",
+    "name": "index",
     "kind": "function",
     "members": {
       "instance": [],
       "static": []
     },
     "path": [
-      "main"
+      "index"
     ]
   }
 ]