Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

POC for JSDoc extraction #182

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

POC for JSDoc extraction #182

wants to merge 1 commit into from

Conversation

fregante
Copy link
Member

@fregante fregante commented Aug 11, 2023

For #146

I found a package that allows extraction of URLs from JSDoc. The issue is that we sometimes have comments around test URLs, which are impractical in JSDoc:

  • while they can be easily filtered out, any deviations from the expected comment position would require future changes to this setup

but mainly:

  • JSDoc are user-facing, but these comments might not make sense outside the source code, e.g.
/** 
 * Some of these are here simply as "gotchas" to other detections
 * @example https://github.com/sindresorhus/refined-github/blame/master/package.json // Gotcha for isRepoTaxonomyIssueOrPRList
 * @example https://github.com/sindresorhus/notifications/
 */

this would show up as the description of the isRepo function, which is not relevant to the final user.

@fregante
Copy link
Member Author

The tool also appears to easily allow editing of the files, so I wouldn't exclude going the other way around:

  • leave index.ts as is but add the JSDoc after the transpilation, directly to dist/index.d.ts

tsConfigFilePath: 'tsconfig.json',
});
const testSourceFiles = project.getSourceFile('index.ts');
for (const tag of testSourceFiles.getSymbol('isRepo').getExport('isRepo').getJsDocTags()) {
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given testSourceFiles.getSymbol('isRepo').getExport('isRepo'), I can't reach the FunctionDeclaration to then call addJsDoc 🤷‍♂️

I knew function expressions were a mistake, I think testSourceFiles.getExportDeclaration('isRepo') would have gotten me there.

@134130
Copy link
Contributor

134130 commented Aug 14, 2023

Really looking forward it. I've researched some typescript AST parsers for this feature and this is really nice.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

2 participants