honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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
This commit is contained in:
Peter Bacon Darwin 2015-04-17 13:50:04 +01:00
parent 87ac100c66
commit a8533b2133
3 changed files with 15 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/dgeni-package/index.js
View File

@ -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({

12
docs/links-package/index.js Normal file
View File

@ -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);
});

4
docs/public-docs-package/index.js
View File

@ -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'))