chore(docs): generate header ids for better linking

- generate ids for all headers
- collect defined anchors
- check broken links (even if the page exists, but the anchor/id does not)

1 files changed, 45 insertions, 18 deletions

diff --git a/docs/src/ngdoc.js b/docs/src/ngdoc.js
index 0f94f6eb..24d1aa26 100644
--- a/docs/src/ngdoc.js
+++ b/docs/src/ngdoc.js
@@ -36,6 +36,7 @@ exports.trim = trim;
 exports.metadata = metadata;
 exports.scenarios = scenarios;
 exports.merge = merge;
+exports.checkBrokenLinks = checkBrokenLinks;
 exports.Doc = Doc;
 
 exports.ngVersions = function() {
@@ -169,6 +170,7 @@ function Doc(text, file, line) {
   this.methods = this.methods || [];
   this.events = this.events || [];
   this.links = this.links || [];
+  this.anchors = this.anchors || [];
 }
 Doc.METADATA_IGNORE = (function() {
   var words = fs.readFileSync(__dirname + '/ignore.words', 'utf8');
@@ -242,6 +244,14 @@ Doc.prototype = {
    * @returns {string} Absolute url
    */
   convertUrlToAbsolute: function(url) {
+    var hashIdx = url.indexOf('#');
+
+    // Lowercase hash parts of the links,
+    // so that we can keep correct API names even when the urls are lowercased.
+    if (hashIdx !== -1) {
+      url = url.substr(0, hashIdx) + url.substr(hashIdx).toLowerCase();
+    }
+
     if (url.substr(-1) == '/') return url + 'index';
     if (url.match(/\//)) return url;
     return this.section + '/' + url;
@@ -569,6 +579,8 @@ Doc.prototype = {
       dom.h('Example', self.example, dom.html);
     });
 
+    self.anchors = dom.anchors;
+
     return dom.toString();
 
     //////////////////////////
@@ -606,7 +618,7 @@ Doc.prototype = {
       dom.html('<a href="api/ngAnimate.$animate">Click here</a> to learn more about the steps involved in the animation.');
     }
     if(params.length > 0) {
-      dom.html('<h2 id="parameters">Parameters</h2>');
+      dom.html('<h2>Parameters</h2>');
       dom.html('<table class="variables-matrix table table-bordered table-striped">');
       dom.html('<thead>');
       dom.html('<tr>');
@@ -660,7 +672,7 @@ Doc.prototype = {
   html_usage_returns: function(dom) {
     var self = this;
     if (self.returns) {
-      dom.html('<h2 id="returns">Returns</h2>');
+      dom.html('<h2>Returns</h2>');
       dom.html('<table class="variables-matrix">');
       dom.html('<tr>');
       dom.html('<td>');
@@ -1211,22 +1223,7 @@ function merge(docs){
   });
 
   for(var i = 0; i < docs.length;) {
-    var doc = docs[i];
-
-    // check links - do they exist ?
-    doc.links.forEach(function(link) {
-      // convert #id to path#id
-      if (link[0] == '#') {
-        link = doc.section + '/' + doc.id.split('#').shift() + link;
-      }
-      link = link.split('#').shift();
-      if (!byFullId[link]) {
-        console.log('WARNING: In ' + doc.section + '/' + doc.id + ', non existing link: "' + link + '"');
-      }
-    });
-
-    // merge into parents
-    if (findParent(doc, 'method') || findParent(doc, 'property') || findParent(doc, 'event')) {
+    if (findParent(docs[i], 'method') || findParent(docs[i], 'property') || findParent(docs[i], 'event')) {
       docs.splice(i, 1);
     } else {
       i++;
@@ -1255,6 +1252,36 @@ function merge(docs){
 }
 //////////////////////////////////////////////////////////
 
+
+function checkBrokenLinks(docs) {
+  var byFullId = Object.create(null);
+
+  docs.forEach(function(doc) {
+    byFullId[doc.section + '/' + doc.id] = doc;
+  });
+
+  docs.forEach(function(doc) {
+    doc.links.forEach(function(link) {
+      // convert #id to path#id
+      if (link[0] == '#') {
+        link = doc.section + '/' + doc.id.split('#').shift() + link;
+      }
+
+      var parts = link.split('#');
+      var pageLink = parts[0];
+      var anchorLink = parts[1];
+      var linkedPage = byFullId[pageLink];
+
+      if (!linkedPage) {
+        console.log('WARNING: ' + doc.section + '/' + doc.id + ' (defined in ' + doc.file + ') points to a non existing page "' + link + '"!');
+      } else if (anchorLink && linkedPage.anchors.indexOf(anchorLink) === -1) {
+        console.log('WARNING: ' + doc.section + '/' + doc.id + ' (defined in ' + doc.file + ') points to a non existing anchor "' + link + '"!');
+      }
+    });
+  });
+}
+
+
 function property(name) {
   return function(value){
     return value[name];