JSDoc 3 Multiple @author tags ignores <email@address> in template output?

[Josh Rhoades]

Just started to notice for that a few methods we have with multiple authors, the email is not rendering out at the template level during processing.

For example, with the JSDoc block like this:

/**

* @author John Doe <john...@smacksalot.com>

* @author John Doe's Daddy <meyou...@grubberface.com>

*/

Results in a template output just like

Author

John Doe

John Doe's Daddy

if I remove the brackets (meyou...@grubberface.com instead of <meyou...@grubberface.com>) the addresses show back up, but the "standard" is emails with angle brackets...sure I could do a global S&R, but if its supposed to work a specific way I'd rather get it that way. Plus I'm doing email address regex detection/formatting and turning them into email buttons, so this inconsistency is making that not work in all cases.

Still trying to track down where in JSDoc 3 the author is being directly parsed and see if there's a formatting issue there that causes this race condition.

[mathematical.coffee]

I've had a quick look into this and it's not only when there are multiple authors - it happens for any author.

If you look at the HTML the email is there:

<li>John Doe <f...@bar.com></li>

The problem is that the < and > are not being escaped by JSDoc (since it allows you to embed HTML into your tags).

You could do:

@author John Doe &lt;f...@bar.com&gt;

and that works.

(Since JSDoc allows HTML in all the tags including @author, perhaps you could write a plugin that automatically does your email address regex detection/formatting and adds the HTML for the email buttons in directly? The plugin would only have to look at the `doclet.author` property (an array of strings) for each doclet).

[Josh Rhoades]

I do have a plugin I wrote that finds email addresses and makes them hot, stripping away the <> surrounds if it finds them. But when there are multiple authors, the plugin doesn't even get to recognize them and fire (disabling the plugin to see if there were any differences was the first thing I checked). So in single author blocks, the author output is fine. In multi-author blocks, the output leaves the formatted email address as an html tag (<em...@domain.com/>), and the plugin can't recognize it. Almost as if there's a slightly different processing going on for multi-author blocks.

Part of me wants to dig in more and find out why there is a difference, though I agree that revising the plugin to be more literal and override the author output completely (instead of just manipulating it) would cover the disparate cases, especially since my team has all followed the "standard" of * @author First Last <em...@domain.com>.

On Friday, January 25, 2013 4:35:59 PM UTC-8, mathematical.coffee wrote:

I've had a quick look into this and it's not only when there are multiple authors - it happens for any author.

If you look at the HTML the email is there:

<li>John Doe <f...@bar.com></li>

The problem is that the < and > are not being escaped by JSDoc (since it allows you to embed HTML into your tags).

You could do:

@author John Doe &lt;...@bar.com&gt;

[Jeff Williams]

This is now working as desired in the default template:

- "@author Jane Doe <jd...@example.org>" will be converted to a mailto: link with the text "Jane Doe."

- "@author Jane Doe <jdoe at example dot org>" will be unchanged, except that the "<" will be replaced with an entity.

This should work regardless of how many authors are specified.

- Jeff

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jsdoc-users...@googlegroups.com.
To post to this group, send email to jsdoc...@googlegroups.com.
Visit this group at http://groups.google.com/group/jsdoc-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Josh Rhoades]

Nice, grabbed those changes and it's all nice and clean now. The only thing I changed was in details.tmpl, since I am dynamically formatting any email link as a CSS3 button, was instead of 

<li><?js= self.resolveAuthorLinks(a) ?></li>

I am doing

<li><?js= self.resolveAuthorLinks(a.replace('<<','<').replace('>>','>')) ?></li>

Otherwise it renders as <CSS3BUTTON> instead of just CSS3BUTTON, but that's unique to my template style's output.

Thanks, Jeff.