This repository was archived by the owner on May 22, 2025. It is now read-only.
Repository navigation
This repository was archived by the owner on May 22, 2025. It is now read-only.
JSDoc annotations are prepended with backslash in externs output #907
Description
I have some JSDoc annotations in the source code, e.g. @link, @example. In the externs output, Most of them are escaped by backslash, and in my example, one annotation was deleted.
Input:
/**
* {@link http://example.com} and
* {@link
* https://example.com} for detailed documentation.
*
* @example
* console.log('hello');
*
* @example
* console.log('hello again');
*
*/
export function hello(): void;Output:, notice that all annotations are prepended with backslash and the second @example is missing.
/**
* @externs
* @suppress {duplicate,checkTypes}
*/
// NOTE: generated by tsickle, do not edit.
// externs from :
/** @const */
var _$$index$d = {};
/**
* {\@link http://example.com} and
* {\@link
* https://example.com} for detailed documentation.
*
* \@example
* console.log('hello');
* /
* console.log('hello again');
*
* @return {void}
*/
_$$index$d.hello = function() {};Is it done this way to avoid conflicts?
Is there a way to keep the comment section as is in the externs?
Activity
mprobst commentedon Oct 11, 2018
This is working as intended - Closure Compiler would complain about
@example, because it is not a standard JSDoc tag. Can you expand on your use case here?Feiyang1 commentedon Oct 11, 2018
We have a set of tools that generate the devsite content from externs. The project is written in TS, so we manually created externs, put comments in it and maintain it as the API changes. It's a pain to maintain and is error prone. I want to move all the comments to d.ts and auto generate the externs from d.ts. It would be great if there is a flag to preserve all comments.
Why was the second @example deleted? if tsickle didn't delete anything, I could run another script to unescape the annotations, but it's not possible since some annotation are deleted.
mprobst commentedon Oct 12, 2018
evmar commentedon Oct 12, 2018
Another way to put this is that tsickle is generating compiler syntax (which happens to be written in a thing that looks like jsdoc) and not human-oriented jsdoc.
I think regexing the output might be a hacky way to solve your problem. I'm not sure about why the @example was deleted, that seems like the sort of bug we might want to fix. (On the other hand under the reasoning of the previous paragraph I'm not sure why we preserve any comment text that isn't a load-bearing compiler statement.)
mprobst commentedon Oct 12, 2018
Feiyang1 commentedon Oct 15, 2018
Thank you for the insight! Is preserving the comments something you would consider? If not, would you consider fixing the deletion of the second @example ?
I haven't looked into tsdoc yet, but it could be a good option. I'm trying to improve the documentation process incrementally, it would be great if tsickle can help to bridge the gap without changing too much as the first step.
evmar commentedon Oct 15, 2018
I'm not sure I can fix this right now, but we'd take a patch if you wrote one.
Edit this file to include your example, run with the the UPDATE_GOLDENs flag in the README, then tinker with src/jsdoc.ts until it does what you want.
https://github.com/angular/tsickle/blob/master/test_files/jsdoc/jsdoc.ts