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

Decorator support in examples? #698

Closed
Ghnuberath opened this issue Mar 18, 2017 · 5 comments

Comments

@Ghnuberath
Copy link

@Ghnuberath Ghnuberath commented Mar 18, 2017

I'm trying to write a jsdoc example with a decorator in it, like so (somewhat truncated example):

/**
 * @example
 * const Module = require('ravel').Module;
 * @inject('path')
 * class MyModule extends Module {
 *   constructor (path) {
 *     super();
 *     this.path = path;
 *   }
 * }
 */

Unfortunately, the resulting example in the docs only contains the const Module line and omits the remainder of the example. My gut says that the parser (doctrine?) is treating the @inject decorator as a new (unrecognized) section within the comment and not as part of the example.

Is there currently an elegant way to 'escape' the @ so that it will be parsed as part of the example?

I'm currently post-processing the html output of documentation with some dirty regex/gulp-replace magic as a workaround to produce the correct hljs markup.

@tmcw

This comment has been minimized.

Copy link
Member

@tmcw tmcw commented Mar 20, 2017

Yep, your diagnosis is on the dot - doctrine is thinking that @inject is a JSDoc tag. I don't see any tickets about this upstream, maybe file one there, since this is something you can reproduce with the doctrine demo?

@tmcw

This comment has been minimized.

Copy link
Member

@tmcw tmcw commented Apr 14, 2017

I can confirm that this issue is shared with the official JSDoc tool as well.

@radiaph

This comment has been minimized.

Copy link

@radiaph radiaph commented Apr 20, 2017

A (certainly non-ideal) workaround is to omit the @example and wrap the code in backticks. This seems to prevent the @ from being interpreted as a JSDoc tag opening.

@chengjianhua

This comment has been minimized.

Copy link

@chengjianhua chengjianhua commented Sep 5, 2017

@radiaph I agree with that backticks is fine.

So how is this going ?

@tmcw

This comment has been minimized.

Copy link
Member

@tmcw tmcw commented Apr 11, 2018

Fixed in #1051

@tmcw tmcw closed this Apr 11, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.