@example should perform escaping

[Joris-van-der-Wel]

/** Perform foo
 * @example foo('<a href="#baz">hi!</a>');
 */
function foo(bar)
{
    return '<strong>' + bar + '</strong>';
};

jsdoc test.js gives me:

<pre class="prettyprint"><code>foo('&lt;a href="#baz">hi!&lt;/a>');</code></pre>

jsdoc2md test.js gives me:

<a name="foo"></a>
#foo()
Perform foo

**Example**
foo('<a href="#baz">hi!</a>');

That anchor is interpreted by markdown as html, this should probably be escaped or wrapped within a code block.

[75lb]

hi.. the example content is deliberately not escaped as some users like to embed real markup in their @example (some people use the output on internal sites which permit markup).. e.g.

/** 
Constructs some UI widget or other
@example
<div data-create-widget="UIWidget"></div>
*/
function UIWidget()
{
    ...
};

now, in their generated documentation, the UIWidget renders inline as desired..

if you want to wrap your example in a code block use the standard markdown syntax of either

/**Perform foo
@example
    foo('<a href="#baz">hi!</a>');
 */
function foo(bar)
{
    return '<strong>' + bar + '</strong>';
};

or

/**Perform foo
@example
`foo('<a href="#baz">hi!</a>');`
 */
function foo(bar)
{
    return '<strong>' + bar + '</strong>';
};

i'm working on the next version of the tool which has options to automatically wrap examples in code blocks, amongst other things

[Joris-van-der-Wel]

Ah, that is what I suspected. However the regular jsdoc (html output) has the opposite behaviour so an option would be indeed be useful. (I want to use both jsdoc and jsdoc2md in the same project)

Thanks

[75lb]

the jsdoc html output might look correct, but if you run jsdoc -X against your code you'll see the issue in the underlying data.. try it: $ jsdoc -X my-code.js

[Joris-van-der-Wel]

Yes I understand, this is why jsdoc does this escaping in the templates:

https://github.com/jsdoc3/jsdoc/blob/b5653b838ce7b96f97322c77e65f74c3086bd3d1/templates/default/tmpl/examples.tmpl#L10

This was added because of https://github.com/jsdoc3/jsdoc/issues/511

[75lb]

hey there, i am testing the next version of the tool against your project - this is how the output currently looks: https://github.com/75lb/domv/blob/master/api.md

any feedback is welcome ;)

[Joris-van-der-Wel]

Awesome, that looks much better.

Here's some things I have noticed:

• Perhaps inherited methods / attributes (@augments) should be listed in their own sublist, just like that new "instance" sublist
• Some of the markdown headings need an extra new line before or after them, see here https://github.com/75lb/domv/blob/master/api.md#external_Node
• Externals are not linked
• @returns {?(module:domv/lib/Component|module:domv/lib/Component[])} is shown as Returns: Component | Array.<module:domv/lib/Component--Component> I am not sure what that -- is. See here https://github.com/75lb/domv/blob/master/api.md#module_domv.wrap

[75lb]

1. good idea :+1:
2. ah yes, thanks
3. yes, i will tackle this
4. true - that needs fixing

thanks! will get back to you..

[75lb]

here are the domv docs generated using the latest jsdoc2md code, how does it look?: https://github.com/75lb/domv/blob/master/api.md

1. implemented.. take a look at domv/lib/HtmlDocument.. if you click an inherited member in the class member index it takes you to the docs in the parent class (Component).. this reduces duplication in the docs (before, docs for inherited Component members were duplicated inside the docs for HtmlDocument)..
2. this was caused by <p> tags in the domv jsdoc documentation that did not have a closing </p>..
3. done
4. done

[Joris-van-der-Wel]

awesome that looks much better! I do not see any other issues, thanks

I committed the missing </p>

[75lb]

good, glad you like it.. i will package up a pre-release of jsdoc2md for you to experiment with.. will get back to you later..