@example does not render in monospace

[Christopher Hiller]

In order to have your @example tag render in monospace, you need to do this:

/** 
 * @description does the damn thing
 * @param {Thing} damnThing Damn thing to do
 * @example
 * ```
 * doThe(damnThing);
 * ```
 */
var doThe = function doThe(damnThing) {
  // does it
});

I would expect @example to render in monospace regardless of the presence of ``` or extra indent.

I have a fix for this which I can probably submit later. Wanted to know if you agreed.

[Lloyd Brookes]

the triple-backtick syntax is Github specific, not everyone is using Github..

i wrote the dmd-examples-highlight for users that wanted this syntax all the time.. generally, specific user tastes can be satisfied by using the --helper, --partial or --plugin options on jsdoc2md.. these options aren't very well documented yet, sorry about that - it is my current priority and main focus..

[Christopher Hiller]

It's not really about the triple-backtick, it's about @example not rendering monospace by default.

[Lloyd Brookes]

To get the monospace you need to indent your code block.. I don't think dmd should indent by default as not all examples are code

[Christopher Hiller]

very well

[Lloyd Brookes]

it's easy to override the default partials to taste, i just haven't had chance to document it yet..

say you have this JS:

/**
a function
@example
var a = doSomething(b);
*/
function doSomething(b){};

this would produce this markdown:

#doSomething()
a function

**Example**
var a = doSomething(b);

to override the example.hbs template, duplicate the file (partials/field/examples.hbs) into your local project, then edit it.. for example, add a 4 space identation:

{{#if examples}}{{#each examples}}**Example**  

    {{{this}}}

{{/each}}{{/if~}}

now run jsdoc2md with the --partial option, passing in your edited partial that you saved locally (warning - filename is significat, it must be examples.hbs):

$ jsdoc2md tmp/example.js --partial tmp/examples.hbs

now you get your desired output:

#doSomething()
a function

**Example**

    var a = doSomething(b);

[Lloyd Brookes]

if you end up overriding several partials, pass them as a list of args, e.g.

$ jsdoc2md --src tmp/example.js --partial examples.hbs description.hbs etc.hbs etc.hbs

[Lloyd Brookes]

if you want to share your overrides with others, bundle them as a plugin for distribution via npm.. will document that too soon..

[Christopher Hiller]

Actually if you want to reconsider, I am only mentioning this because it's the default jsdoc behavior and people expect it to work this way.

From the jsdoc API documentation:

Provide an example of how to use a documented item. The text that follows this tag will be displayed as highlighted code.

People are going to read the API docs, wonder why dmd doesn't do it this way, and think the bug is in dmd (which, in my opinion, it is).

Your argument is that the example might not be code. What else would it be? If you need to write something other than code, use comments--that's what I do.

/** 
 * @description does the damn thing
 * @param {Thing} damnThing Damn thing to do
 * @example
 * 
 * // this is how you use the damn thing
 * doThe(damnThing);
 * 
 */
var doThe = function doThe(damnThing) {
  // does it
});

I'm just kind of loathe to start adding custom templates to something that should have sensible defaults out-of-the-box. I can understand if I wanted my Markdown to look different, then I'd need a custom template, but an @example tag is supposed to be code, no matter what it's rendered with.

[Lloyd Brookes]

i know, i agree.. but if i default to outputting @examples with (say) 4-space indentation there will be people that say, "but i want to force ruby syntax highlighting using triple-backtick ruby gfm syntax".. they add that to their own @examples and end up with output that has been formatted twice, once by them, and again by the sane default.. (this results in unwanted indentation within a triple-backtick block - try it)

my first @example template had built-in gfm formatting, but it soon became an issue (users wanting control).. that's why making overrides easy is fundamental - it's impossible to satisfy everyone..

[Lloyd Brookes]

i agree that sane defaults are always good.. i will do something about this - maybe i could make a plugin that removes the sane default of triple-backtick, rather than adding it

[Christopher Hiller]

You mean ruby syntax highlighting in a jsdoc example? Sounds like an edge case...

No, you can't satisfy everyone, and yeah that's why should be easy to override. I agree. Just think the default should be preformatted. Whether it comes out as four spaces or backticks, I don't really care...