JSDoc annotations are prepended with backslash in externs output

[Feiyang1]

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?

[mprobst]

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]

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]

Interesting. That's not really a use case we've been thinking about - we only intend for Closure Compiler to consume these JSDoc annotations. That's why were doing a bunch of transformations to them to make them Closure compliant. Those transformations are probably not what you want for a generic JSDoc consumer like the JSDoc implementation itself. I'm not sure tsickle is the right tool for you to being with. Have you considered adopting something that works from the TS source directly, e.g. https://github.com/Microsoft/tsdoc ?

[evmar]

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]

I suspect we might have collated the different @example tag content blocks together? Not sure.

[Feiyang1]

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]

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