honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
angular-cn/aio/tools/transforms/angular-api-package/processors/collectPackageContentDocs.s...

50 lines
2.4 KiB
JavaScript
Raw Normal View History

build(docs-infra): support doc aliases via `@alias` dgeni tag (#29673) Now, one can add an `@alias` tag to API docs, which tells dgeni that this API element (usually a `const`) is really just an alias for some API element defined elsewhere. Dgeni will then look up this API element and copy over the properties from the alias to the current doc. For example, we would like to privately export an Enum from `@angular/core` but then publicly export this from `@angular/common`: **packages/core/private_exports.ts** ```ts /** * Description of this document. */ export enum ɵSomeEnum { ... } ``` **packages/common/public_api.ts** ```ts import {ɵSomeEnum} from '@angular/core'; /** * @alias core/ɵSomeEnum */ export const SomeEnum = ɵSomeEnum; ``` In the generated docs there will be a page for `common/SomeEnum`, which will be rendered as an enum, rather than a const, showing the description extracted from the `core/ɵSomeEnum`. --- The implementation of this feature required some refactoring of the other processing: 1. Previously `ɵ` prefixed exports were not even considered. 2. Due to 1. some processors needed to have guards added to ignore such private exports (`addMetadataAliases` and `checkContentRules`). 3. The processing of package pages had to be reworked (and split) so that it picked up the aliased export docs after their alias proeprties had been copied. See FW-1207, FW-632, #29249 PR Close #29673
2019-04-02 17:24:29 -04:00
const testPackage = require('../../helpers/test-package');
const processorFactory = require('./collectPackageContentDocs');
const Dgeni = require('dgeni');
describe('collectPackageContentDocs processor', () => {
it('should be available on the injector', () => {
const dgeni = new Dgeni([testPackage('angular-api-package')]);
const injector = dgeni.configureInjector();
const processor = injector.get('collectPackageContentDocsProcessor');
expect(processor.$process).toBeDefined();
expect(processor.$runAfter).toEqual(['tags-extracted']);
expect(processor.$runBefore).toEqual(['computing-ids', 'processPackages']);
});
it('should collect any `package-content` docs in the `packageContentFiles` map', () => {
const docs = [
{ fileInfo: { filePath: 'some/a' }, docType: 'a', id: 'a' },
{ fileInfo: { filePath: 'some/x/PACKAGE.md' }, docType: 'package-content', id: 'x' },
{ fileInfo: { filePath: 'some/b' }, docType: 'b', id: 'b' },
{ fileInfo: { filePath: 'some/y/PACKAGE.md' }, docType: 'package-content', id: 'y' },
{ fileInfo: { filePath: 'some/z/PACKAGE.md' }, docType: 'package-content', id: 'z' },
];
const processor = processorFactory();
processor.$process(docs);
expect(processor.packageContentFiles).toEqual({
'some/x': { fileInfo: { filePath: 'some/x/PACKAGE.md' }, docType: 'package-content', id: 'x' },
'some/y': { fileInfo: { filePath: 'some/y/PACKAGE.md' }, docType: 'package-content', id: 'y' },
'some/z': { fileInfo: { filePath: 'some/z/PACKAGE.md' }, docType: 'package-content', id: 'z' },
});
});
it('should filter out any `package-content` docs from the collection', () => {
const docs = [
{ fileInfo: { filePath: 'some/a' }, docType: 'a', id: 'a' },
{ fileInfo: { filePath: 'some/x/PACKAGE.md' }, docType: 'package-content', id: 'x' },
{ fileInfo: { filePath: 'some/b' }, docType: 'b', id: 'b' },
{ fileInfo: { filePath: 'some/y/PACKAGE.md' }, docType: 'package-content', id: 'y' },
{ fileInfo: { filePath: 'some/z/PACKAGE.md' }, docType: 'package-content', id: 'z' },
];
const processor = processorFactory();
const newDocs = processor.$process(docs);
expect(newDocs).toEqual([
{ fileInfo: { filePath: 'some/a' }, docType: 'a', id: 'a' },
{ fileInfo: { filePath: 'some/b' }, docType: 'b', id: 'b' },
]);
});
});