Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(compiler): add docs extraction for type aliases (#52118)
This commit adds support for extracting type alises. It currently extracts the raw written type from the source without performing any resolution, such as for resolving `typeof` queries, as current Angular public APIs do not rely on this. PR Close #52118
- Loading branch information
Showing
4 changed files
with
96 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
27 changes: 27 additions & 0 deletions
27
packages/compiler-cli/src/ngtsc/docs/src/type_alias_extractor.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
/** | ||
* @license | ||
* Copyright Google LLC All Rights Reserved. | ||
* | ||
* Use of this source code is governed by an MIT-style license that can be | ||
* found in the LICENSE file at https://angular.io/license | ||
*/ | ||
import ts from 'typescript'; | ||
|
||
import {EntryType} from './entities'; | ||
import {extractJsDocDescription, extractJsDocTags, extractRawJsDoc} from './jsdoc_extractor'; | ||
|
||
/** Extract the documentation entry for a type alias. */ | ||
export function extractTypeAlias(declaration: ts.TypeAliasDeclaration) { | ||
// TODO: this does not yet resolve type queries (`typeof`). We may want to | ||
// fix this eventually, but for now it does not appear that any type aliases in | ||
// Angular's public API rely on this. | ||
|
||
return { | ||
name: declaration.name.getText(), | ||
type: declaration.type.getText(), | ||
entryType: EntryType.TypeAlias, | ||
rawComment: extractRawJsDoc(declaration), | ||
description: extractJsDocDescription(declaration), | ||
jsdocTags: extractJsDocTags(declaration), | ||
}; | ||
} |
61 changes: 61 additions & 0 deletions
61
packages/compiler-cli/test/ngtsc/doc_extraction/type_alias_doc_extraction_spec.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,61 @@ | ||
/** | ||
* @license | ||
* Copyright Google LLC All Rights Reserved. | ||
* | ||
* Use of this source code is governed by an MIT-style license that can be | ||
* found in the LICENSE file at https://angular.io/license | ||
*/ | ||
|
||
import {DocEntry} from '@angular/compiler-cli/src/ngtsc/docs'; | ||
import {EntryType, TypeAliasEntry} from '@angular/compiler-cli/src/ngtsc/docs/src/entities'; | ||
import {runInEachFileSystem} from '@angular/compiler-cli/src/ngtsc/file_system/testing'; | ||
import {loadStandardTestFiles} from '@angular/compiler-cli/src/ngtsc/testing'; | ||
|
||
import {NgtscTestEnvironment} from '../env'; | ||
|
||
const testFiles = loadStandardTestFiles({fakeCore: true, fakeCommon: true}); | ||
|
||
runInEachFileSystem(os => { | ||
let env!: NgtscTestEnvironment; | ||
|
||
describe('ngtsc type alias docs extraction', () => { | ||
beforeEach(() => { | ||
env = NgtscTestEnvironment.setup(testFiles); | ||
env.tsconfig(); | ||
}); | ||
|
||
it('should extract type aliases based on primitives', () => { | ||
env.write('index.ts', ` | ||
export type SuperNumber = number | string; | ||
`); | ||
|
||
const docs: DocEntry[] = env.driveDocsExtraction('index.ts'); | ||
expect(docs.length).toBe(1); | ||
|
||
const typeAliasEntry = docs[0] as TypeAliasEntry; | ||
expect(typeAliasEntry.name).toBe('SuperNumber'); | ||
expect(typeAliasEntry.entryType).toBe(EntryType.TypeAlias); | ||
expect(typeAliasEntry.type).toBe('number | string'); | ||
}); | ||
|
||
it('should extract type aliases for objects', () => { | ||
env.write('index.ts', ` | ||
export type UserProfile = { | ||
name: string; | ||
age: number; | ||
}; | ||
`); | ||
|
||
const docs: DocEntry[] = env.driveDocsExtraction('index.ts'); | ||
expect(docs.length).toBe(1); | ||
|
||
const typeAliasEntry = docs[0] as TypeAliasEntry; | ||
expect(typeAliasEntry.name).toBe('UserProfile'); | ||
expect(typeAliasEntry.entryType).toBe(EntryType.TypeAlias); | ||
expect(typeAliasEntry.type).toBe(`{ | ||
name: string; | ||
age: number; | ||
}`); | ||
}); | ||
}); | ||
}); |