feat(compiler): extract doc info for JsDoc #51717
Conversation
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#51685 This expands on the extraction with information for directives, including inputs and outputs. As part of this change, I've refactored the extraction code related to class and to directives into their own extractor classes to more cleanly separate extraction logic based on type of statement.
Based on top of angular#51697 Adds extraction for accessors (getters/setters), rest params, and resolved type info for everything so far. This also refactors function extraction into a new class and splits tests for common class info and directive info into separate files.
Based on top of #angular#51700 Also updates extraction to ignore un-exported statements.
jelbourn
added
area: compiler
| * Save some data. | ||
| * @param data The data to save. | ||
| * @param timing Long description | ||
| * with multiple lines. |
There was a problem hiding this comment.
Can we add another scenario where after the multi-line string another tag is set? Would be good to ensure TS properly handles this. e.g.
/**
* Save some data.
* @param data The data to save.
* @param timing Long description
* with multiple lines.
* @param bla Long description 2
* with multiple times
*/
|
|
||
| it('should extract a @see jsdoc tag', () => { | ||
| // "@see" has special behavior with links, so we have tests | ||
| // specifically for this tag. |
There was a problem hiding this comment.
what's the special behavior in terms of parsing? is the extra space you're talking about later in the expect?
There was a problem hiding this comment.
I still need to spend more time figuring out the behavior of @see; I figured it would be more useful to do that later in the process, though, once we're actually doing something to make cross-links work. Trying something like
/**
* Future version.
* @see Component
*/
weirdly returns {name: 'see', comment: '*'}, even though that's supposed to be valid JsDoc. For the test case here (@see {@link Component}), comment is actually two separate nodes, presumably one for @link and one for Component, but I wasn't yet able to figure out anything to do with those nodes other than put them back to a string with getTextOfJSDocComment.
| @@ -40,10 +40,18 @@ export enum MemberTags { | |||
| Output = 'output', | |||
| } | |||
|
|
|||
| export interface JsDocTagEntry { | |||
| name: string; | |||
| comment: string; | |||
There was a problem hiding this comment.
would it be more accurate to name this text/value?
There was a problem hiding this comment.
I was trying to align with TypeScript's naming here, which is tagName and comment. (the tag part seemed redundant, though)
| // In the TS AST, the leading comment for a variable declaration is actually | ||
| // on the ancestor `ts.VariableStatement` (since a single variable statement may | ||
| // contain multiple variable declarations). | ||
| const rawComment = extractRawJsDoc(declaration.parent.parent); |
There was a problem hiding this comment.
I can't think of a VariableDeclaration outside of a variable list, statement- but would you want to assert this? I think that would make this code more robust and avoid future hard-to-debug scenarios?
There was a problem hiding this comment.
The type of declaration.parent.parent here is ts.VariableStatement | ts.ForStatement | ts.ForOfStatement | ts.ForInStatement | ts.TryStatement. In the scenario that this code path runs for a for or try statement, I think the current behavior (an empty string if the node doesn't have any JsDoc) is reasonable.
I also expect to need to refine things once I start running it over the real sources.
There was a problem hiding this comment.
Sounds good. Just thought might make things easier to debug if we had an actual runtime assert here
Based on top of angular#51713 This commit adds docs extraction for information provided in JsDoc comments, including descriptions and Jsdoc tags.
jelbourn
force-pushed
the
api-gen-jsdoc
branch
from
2e58372
to
6b91f2f
Compare
Based on top of angular#51717 This commit adds extraction for enums, pipes, and NgModules. It also adds a couple of tests for JsDoc extraction that weren't covered in the previous commit.
Based on top of angular#51717 This commit adds extraction for enums, pipes, and NgModules. It also adds a couple of tests for JsDoc extraction that weren't covered in the previous commit.
Based on top of angular#51717 This commit adds extraction for enums, pipes, and NgModules. It also adds a couple of tests for JsDoc extraction that weren't covered in the previous commit.
|
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. |
Based on top of #51713
This commit adds docs extraction for information provided in JsDoc comments, including descriptions and Jsdoc tags.