Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

[superseded] chore(api doc gen): reduce false positives #1846

Closed
wants to merge 1 commit into from
Closed

[superseded] chore(api doc gen): reduce false positives #1846

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions tools/api-builder/angular.io-package/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,14 @@ module.exports = new Package('angular.io', [basePackage, targetPackage, cheatshe

.config(function(getLinkInfo) {
getLinkInfo.useFirstAmbiguousLink = false;
// TODO(chalin): remove once the deprecated angular modules are dropped.
getLinkInfo.resolveAmbiguityForDeprecatedModules = true;
// TODO(chalin): remove the following once this issue is fixed:
// https://github.com/angular/dgeni-packages/issues/192
getLinkInfo.isInvalidLinkOk = function (url, doc) {
return (url === 'CanActivateAnnotation' || url === 'RouteConfigAnnotation') &&
doc && doc.path.includes('router-deprecated');
}
})


Expand Down
5 changes: 2 additions & 3 deletions tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,7 @@ module.exports = function addNotYetDocumentedProperty(EXPORT_DOC_TYPES, log, cre
}

if (doc.notYetDocumented) {
// TODO: (ericjim) should I remove this?
log.warn(createDocMessage("Not yet documented", doc));
log.info(createDocMessage("Not yet documented", doc));
}
});

Expand All @@ -35,4 +34,4 @@ module.exports = function addNotYetDocumentedProperty(EXPORT_DOC_TYPES, log, cre

function notYetDocumented(doc) {
return !doc.noDescription && doc.description.trim().length == 0;
}
}
42 changes: 35 additions & 7 deletions tools/api-builder/links-package/services/getLinkInfo.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,30 @@ var path = require('canonical-path');
*/
module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {

var deprecatedModuleName, indexOfDepDoc = -1, indexOfOtherDoc = -1;

function isAmbiguityOk(docs) {
if (docs.length != 2) return false;

// Tolerate deprecated modules having an ambiguity with its non-deprecated counterpart.
docs.forEach(function (doc, index) {
var matches = doc.fileInfo.relativePath.match(/\/(\w+)-deprecated\//);
if (matches) {
deprecatedModuleName = matches[1];
indexOfDepDoc = index;
} else {
indexOfOtherDoc = index;
}
});
return indexOfDepDoc >= 0 &&
docs[indexOfOtherDoc].fileInfo.relativePath.match(new RegExp('\/'+deprecatedModuleName+'\/'));
}

// Assumes that isAmbiguityOk(docs) has just been invoked.
function ambiguityResolver(docs, url) {
return url.indexOf('-deprecated') < 0 ? indexOfOtherDoc : indexOfDepDoc;
}

return function getLinkInfoImpl(url, title, currentDoc) {
var linkInfo = {
url: url,
Expand All @@ -26,8 +50,9 @@ module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {
}

var docs = getDocFromAlias(url, currentDoc);
var isAmbOk = getLinkInfoImpl.resolveAmbiguityForDeprecatedModules && isAmbiguityOk(docs);

if ( !getLinkInfoImpl.useFirstAmbiguousLink && docs.length > 1 ) {
if ( !getLinkInfoImpl.useFirstAmbiguousLink && docs.length > 1 && !isAmbOk ) {

linkInfo.valid = false;
linkInfo.errorType = 'ambiguous';
Expand All @@ -36,16 +61,17 @@ module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {

} else if ( docs.length >= 1 ) {

linkInfo.url = docs[0].path;
linkInfo.title = title || encodeCodeBlock(docs[0].name, true);
const i = isAmbOk ? ambiguityResolver(docs, url) : 0;
linkInfo.url = docs[i].path;
linkInfo.title = title || encodeCodeBlock(docs[i].name, true);
linkInfo.type = 'doc';

if ( getLinkInfoImpl.relativeLinks && currentDoc && currentDoc.path ) {
var currentFolder = path.dirname(currentDoc.path);
var docFolder = path.dirname(linkInfo.url);
var relativeFolder = path.relative(path.join('/', currentFolder), path.join('/', docFolder));
linkInfo.url = path.join(relativeFolder, path.basename(linkInfo.url));
log.debug(currentDoc.path, docs[0].path, linkInfo.url);
log.debug(currentDoc.path, docs[i].path, linkInfo.url);
}

} else if ( url.indexOf('#') > 0 ) {
Expand All @@ -56,9 +82,11 @@ module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {

} else if ( url.indexOf('/') === -1 && url.indexOf('#') !== 0 ) {

linkInfo.valid = false;
linkInfo.errorType = 'missing';
linkInfo.error = 'Invalid link (does not match any doc): "' + url + '"';
if ( getLinkInfoImpl.isInvalidLinkOk && !getLinkInfoImpl.isInvalidLinkOk(url, currentDoc) ) {
linkInfo.valid = false;
linkInfo.errorType = 'missing';
linkInfo.error = 'Invalid link (does not match any doc): "' + url + '"';
}

} else {

Expand Down