cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

build(docs-infra): support doc aliases via @alias dgeni tag (#29673)

Browse Source 
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
This commit is contained in:
Pete Bacon Darwin
2019-04-02 22:24:29 +01:00
committed by Jason Aden
parent 6233cd55f7
commit a4f3f3f81d
13 changed files with 297 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
aio/tools/transforms/angular-api-package/processors/processPackages.spec.js
View File

@ -9,36 +9,19 @@ describe('processPackages processor', () => {
const injector = dgeni.configureInjector();
const processor = injector.get('processPackages');
expect(processor.$process).toBeDefined();
expect(processor.$runAfter).toEqual(['extractDecoratedClassesProcessor', 'computeStability']);
expect(processor.$runBefore).toEqual(['computing-ids', 'generateKeywordsProcessor']);
expect(processor.$runAfter).toEqual(['processAliasDocs', 'collectPackageContentDocsProcessor']);
expect(processor.$runBefore).toEqual(['rendering-docs', 'checkContentRules']);
});
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' }, docType: 'package-content', id: 'x' },
{ fileInfo: { filePath: 'some/b' }, docType: 'b', id: 'b' },
{ fileInfo: { filePath: 'some/y' }, docType: 'package-content', id: 'y' },
{ fileInfo: { filePath: 'some/z' }, 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' },
]);
});
it('should change `module` docs to `package` docs', () => {
const processor = processorFactory();
const processor = processorFactory({ packageContentFiles: {} });
const docs = [
{ fileInfo: { filePath: 'some/a' }, docType: 'module', id: 'a' },
{ fileInfo: { filePath: 'some/b' }, docType: 'module', id: 'b' },
{ docType: 'other', id: 'c' },
];
const newDocs = processor.$process(docs);
expect(newDocs).toEqual([
processor.$process(docs);
expect(docs).toEqual([
jasmine.objectContaining({ docType: 'package', id: 'a' }),
jasmine.objectContaining({ docType: 'package', id: 'b' }),
jasmine.objectContaining({ docType: 'other', id: 'c' }),
@ -54,21 +37,23 @@ describe('processPackages processor', () => {
someProp: 'foo',
},
{
fileInfo: { filePath: 'some/package-2/index' },
docType: 'module',
id: 'package-2',
},
];
const packageContentFiles = {
'some/package-1': {
fileInfo: { filePath: 'some/package-1/PACKAGE.md' },
docType: 'package-content',
id: 'package-1/PACKAGE.md',
shortDescription: 'some short description',
description: 'some description',
see: [ 'a', 'b' ],
},
{
fileInfo: { filePath: 'some/package-2/index' },
docType: 'module',
id: 'package-2',
},
];
const processor = processorFactory();
const newDocs = processor.$process(docs);
}
};
const processor = processorFactory({ packageContentFiles });
processor.$process(docs);
const package1 = jasmine.objectContaining({
fileInfo: { filePath: 'some/package-1/PACKAGE.md' },
@ -90,7 +75,7 @@ describe('processPackages processor', () => {
isPrimaryPackage: true,
});
expect(newDocs).toEqual([package1, package2]);
expect(docs).toEqual([package1, package2]);
});
it('should compute primary and second package info', () => {
@ -111,20 +96,20 @@ describe('processPackages processor', () => {
id: 'package-1/sub-2',
},
];
const processor = processorFactory();
const newDocs = processor.$process(docs);
const processor = processorFactory({ packageContentFiles: {} });
processor.$process(docs);
expect(newDocs[0].isPrimaryPackage).toBe(true);
expect(newDocs[1].isPrimaryPackage).toBe(false);
expect(newDocs[2].isPrimaryPackage).toBe(false);
expect(docs[0].isPrimaryPackage).toBe(true);
expect(docs[1].isPrimaryPackage).toBe(false);
expect(docs[2].isPrimaryPackage).toBe(false);
expect(newDocs[0].packageInfo.primary).toBe(newDocs[0]);
expect(newDocs[1].packageInfo.primary).toBe(newDocs[0]);
expect(newDocs[2].packageInfo.primary).toBe(newDocs[0]);
expect(docs[0].packageInfo.primary).toBe(docs[0]);
expect(docs[1].packageInfo.primary).toBe(docs[0]);
expect(docs[2].packageInfo.primary).toBe(docs[0]);
expect(newDocs[0].packageInfo.secondary).toEqual([newDocs[1], newDocs[2]]);
expect(newDocs[1].packageInfo.secondary).toEqual([newDocs[1], newDocs[2]]);
expect(newDocs[2].packageInfo.secondary).toEqual([newDocs[1], newDocs[2]]);
expect(docs[0].packageInfo.secondary).toEqual([docs[1], docs[2]]);
expect(docs[1].packageInfo.secondary).toEqual([docs[1], docs[2]]);
expect(docs[2].packageInfo.secondary).toEqual([docs[1], docs[2]]);
});
it('should partition the exports of packages into groups, sorted by id', () => {
@ -150,28 +135,28 @@ describe('processPackages processor', () => {
]
},
];
const processor = processorFactory();
const newDocs = processor.$process(docs);
const processor = processorFactory({ packageContentFiles: {} });
processor.$process(docs);
expect(newDocs[0].decorators).toEqual([
expect(docs[0].decorators).toEqual([
{ docType: 'decorator', id: 'decorator-1' },
]);
expect(newDocs[0].functions).toEqual([
expect(docs[0].functions).toEqual([
{ docType: 'function', id: 'function-1' },
]);
expect(newDocs[0].structures).toEqual([
expect(docs[0].structures).toEqual([
{ docType: 'enum', id: 'enum-1' },
{ docType: 'interface', id: 'interface-1' },
{ docType: 'interface', id: 'interface-2' },
]);
expect(newDocs[0].directives).toEqual([
expect(docs[0].directives).toEqual([
{ docType: 'directive', id: 'directive-1' },
{ docType: 'directive', id: 'directive-2' },
]);
expect(newDocs[0].pipes).toEqual([
expect(docs[0].pipes).toEqual([
{ docType: 'pipe', id: 'pipe-1' },
]);
expect(newDocs[0].types).toEqual([
expect(docs[0].types).toEqual([
{ docType: 'const', id: 'const-1' },
{ docType: 'const', id: 'const-2' },
{ docType: 'type-alias', id: 'type-alias-1' },
@ -215,13 +200,13 @@ describe('processPackages processor', () => {
]
},
];
const processor = processorFactory();
const newDocs = processor.$process(docs);
const processor = processorFactory({ packageContentFiles: {} });
processor.$process(docs);
expect(newDocs[0].deprecated).toBeTruthy();
expect(newDocs[1].deprecated).toBeTruthy();
expect(newDocs[2].deprecated).toBeUndefined();
expect(newDocs[3].deprecated).toBeUndefined();
expect(docs[0].deprecated).toBeTruthy();
expect(docs[1].deprecated).toBeTruthy();
expect(docs[2].deprecated).toBeUndefined();
expect(docs[3].deprecated).toBeUndefined();
});
it('should compute the deprecated status of packages', () => {
@ -275,12 +260,12 @@ describe('processPackages processor', () => {
]
},
];
const processor = processorFactory();
const newDocs = processor.$process(docs);
expect(newDocs[0].packageDeprecated).toBe(true);
expect(newDocs[1].packageDeprecated).toBeUndefined();
expect(newDocs[2].packageDeprecated).toBe(false);
expect(newDocs[3].packageDeprecated).toBeUndefined();
expect(newDocs[4].packageDeprecated).toBe(false);
const processor = processorFactory({ packageContentFiles: {} });
processor.$process(docs);
expect(docs[0].packageDeprecated).toBe(true);
expect(docs[1].packageDeprecated).toBeUndefined();
expect(docs[2].packageDeprecated).toBe(false);
expect(docs[3].packageDeprecated).toBeUndefined();
expect(docs[4].packageDeprecated).toBe(false);
});
});