feat(compiler): initial skeleton for API doc extraction#51682
feat(compiler): initial skeleton for API doc extraction#51682jelbourn wants to merge 1 commit intoangular:mainfrom
Conversation
There was a problem hiding this comment.
| let entries: DocEntry[] = []; | |
| for (const sourceFile of this.inputProgram.getSourceFiles()) { | |
| // We don't want to generate docs for `.d.ts` files. | |
| if (sourceFile.isDeclarationFile) continue; | |
| entries = entries.concat(docsExtractor.extract(sourceFile)); | |
| } | |
| return entries; | |
| const entries: DocEntry[] = []; | |
| for (const sourceFile of this.inputProgram.getSourceFiles()) { | |
| // We don't want to generate docs for `.d.ts` files. | |
| if (sourceFile.isDeclarationFile) continue; | |
| entries.push(...docsExtractor.extract(sourceFile)); | |
| } | |
| return entries; |
I'm not sure if there's a specific style in the compiler code for concat vs push, but certainly push is used a lot more. I'm feeling like this should just be push instead.
There was a problem hiding this comment.
I had mentioned in one of Paul's comments; I used concat because my understanding was that it's usually faster than destructuring. Changed it, though, since I don't feel strongly enough and any given source file is unlikely to have more than a few stop-level statements anyway.
There was a problem hiding this comment.
nit: push instead of concat
There was a problem hiding this comment.
This gets changed in one of the follow-up PRs, so I'm going to leave it for this commit
There was a problem hiding this comment.
nit: avoid !
since the guard is outside this function, it was a bit hard to tell that we knew this wasn't null or undefined. Maybe move the guard into this helper function and change the return to DocEntry|null?
There was a problem hiding this comment.
This is just a temporary line for the skeleton that pulls the simplest thing to show we're pulling a bit of data; it gets completely replaced in the next commit
There was a problem hiding this comment.
Should getApiDocumentation be added to the api.Program interface?
Going a bit further (maybe another PR), I'm wondering if createProgram should just return NgtscProgram and we can remove the interface altogether. The documentation at the top of NgtscProgram indicates that the interface was used to maintain compatibility with tooling that relied on a View Engine interface.
There was a problem hiding this comment.
For now I'm just focused on pulling all of the data we care about for docs. Once we're at the point where we want to hook this up, we can figure out what "real" API we actually want the compiler to expose.
This commit adds a barebones skeleton for extracting information to be used for extracting info that can be used for API reference generation. Subsequent PRs will expand on this with increasingly real extraction. I started with @alxhub's angular#51615 and very slightly polished to get to this minimal commit.
Based on top of angular#51682 This expands on the skeleton previously added to extract docs info for classes, including properties, methods, and method parameters. Type information and Angular-specific info (e.g. inputs) will come in future PRs.
Based on top of angular#51682 This expands on the skeleton previously added to extract docs info for classes, including properties, methods, and method parameters. Type information and Angular-specific info (e.g. inputs) will come in future PRs.
|
Changes merged in #51733 |
|
This issue has been automatically locked due to inactivity. Read more about our automatic conversation locking policy. This action has been performed automatically by a bot. |
This commit adds a barebones skeleton for extracting information to be used for extracting info that can be used for API reference generation. Subsequent PRs will expand on this with increasingly real extraction. I started with @alxhub's #51615 and very slightly polished to get to this minimal commit.