From a8533b2133eee28875bab183010a401dedc53d91 Mon Sep 17 00:00:00 2001
From: Peter Bacon Darwin <pete@bacondarwin.com>
Date: Fri, 17 Apr 2015 13:50:04 +0100
Subject: [PATCH] chore(doc-gen): add link inline tags

This commit enables links to other docs, such as classes and modules,
via the `{@link CodeIdentifier}` style inline tag.

Dgeni identifies what you are linking to by comparing the identifier to the
aliases for each doc. If no alias matches the identifier then the dgeni
run exits with a missing doc in link error. If more than one alias matches
the identifier then dgeni exits with an ambiguous link error.

In the future we could build in some heuristics for choosing a preferred
doc when the link is ambiguous, such as choosing a public doc over a
non-public doc; and choosing a code component that is in the same module as
the doc where the link is found.

Currently there are two aliases for each API component: its name and its
identier. For example, if the `Directive` class is exported from
`angular2/annotations`, so its aliases are 'Directive' and
`angular2/annotations.Directive`.

There is an issue in the non-public doc generation, which means that it
does not yet have `{@link}` tags implemented. This is that when we re-export
a code component, it gets cloned into another module. This means that a
simple reference to the code component's name will always produce an
ambiguous link. This can be fixed with a heuristic as described above.
Meanwhile you can avoid this by always using the full id of the code
component if it is being re-exported.

Closes #1371
Closes #1421
---
 docs/dgeni-package/index.js       |  2 +-
 docs/links-package/index.js       | 12 ++++++++++++
 docs/public-docs-package/index.js |  4 ++--
 3 files changed, 15 insertions(+), 3 deletions(-)
 create mode 100644 docs/links-package/index.js

diff --git a/docs/dgeni-package/index.js b/docs/dgeni-package/index.js
index 58b42197c9..b520d8f970 100644
--- a/docs/dgeni-package/index.js
+++ b/docs/dgeni-package/index.js
@@ -107,7 +107,7 @@ module.exports = new Package('angular', [jsdocPackage, nunjucksPackage])
   computeIdsProcessor.idTemplates.push({
     docTypes: EXPORT_DOC_TYPES,
     idTemplate: '${moduleDoc.id}.${name}',
-    getAliases: function(doc) { return [doc.id]; }
+    getAliases: function(doc) { return [doc.id, doc.name]; }
   });
 
   computeIdsProcessor.idTemplates.push({
diff --git a/docs/links-package/index.js b/docs/links-package/index.js
new file mode 100644
index 0000000000..86a835f19c
--- /dev/null
+++ b/docs/links-package/index.js
@@ -0,0 +1,12 @@
+var Package = require('dgeni').Package;
+
+module.exports = new Package('links', [])
+
+.factory(require('dgeni-packages/ngdoc/inline-tag-defs/link'))
+.factory(require('dgeni-packages/ngdoc/services/getAliases'))
+.factory(require('dgeni-packages/ngdoc/services/getDocFromAlias'))
+.factory(require('dgeni-packages/ngdoc/services/getLinkInfo'))
+
+.config(function(inlineTagProcessor, linkInlineTagDef) {
+  inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef);
+});
diff --git a/docs/public-docs-package/index.js b/docs/public-docs-package/index.js
index dbc3c9fcf1..60aac499ea 100644
--- a/docs/public-docs-package/index.js
+++ b/docs/public-docs-package/index.js
@@ -1,8 +1,8 @@
 var Package = require('dgeni').Package;
 var basePackage = require('../dgeni-package');
+var linksPackage = require('../links-package');
 
-
-module.exports = new Package('angular-public', [basePackage])
+module.exports = new Package('angular-public', [basePackage, linksPackage])
 
 .processor(require('./processors/filterPublicDocs'))