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
keep braces and brackets in tags comment. #1001
Conversation
The replacement is done to remove types inside the braces for projects migrating from pure JS and JSDoc. They should be removed in a comment like this: /**
* @param {string} name - the name
*/
function func(name: string) {} I recognize your issue is still a problem, but this shouldn't be how it is addressed. I think changing the first regular expression to ignore braces with tags inside should be the solution. As an aside, I have no clue why the second line there exists. It removes pairs of single brackets, but not double brackets (I'm guessing because they are used for links?), but doesn't remove them if there is nothing between them ( Also, while the description of why you removed the lines is helpful, that should go in the PR, not in the source code. If there were a dozen lines of comments describing how each line was changed the code would quickly become unreadable. Someone who wonders what changed can use |
Hi, @Gerrit0
Are there any requirements on "remove the JSDoc annotatios in tags"? IMHO, the tool should obey user's content. Maybe our tool did too much to our user.
The square brackets in JSDoc is "Optional Params" The only thing I found is this page, please search "optional" on this page.
Very sorry for that. This is my work style, and I don't know GitHub users discuss in PR but don't provide information in code. What's your Opinion on the first two issues? Thanks for your TypeDoc! |
@capraynor Thanks for being willing to discuss this.
I would say yes because we want to separate the JSDoc annotations from the string descriptions. We already show types (from TypeScript) so we don't want the type to appear again from the JSDoc comment. This would result in output similar to the below. You do raise a valid question of whether TypeDoc is doing too much. Looking at the page you liked to, there is a lot of variation in JSDoc syntax which we don't account for (including square brackets for optional params). A few things come to mind:
|
TypeScript does parse JSDoc, but the result is stored on the internal Once we eventually start using |
@capraynor consider just improving these regexps to keep TypeDoc annotations and remove JSDoc annotations, so everyone wins |
I pulled in this fix with a couple changes in eefdb2c, released in 0.16.10. The Sorry this took so long! |
Please see the comments in code.
I just saw some bad code in 2015.
These two lines of code removes braces and square-brackets in tags comment.
This metod only used in parsing tag's comment, so we think tha these two lines of code should be removed.
Another question is, could you please create a hot-fix for us? we eagerly need this thing to be fixed.
Looking forward for your reply
Thousand Thanks!