jsdoc3/jsdoc — pull request #297 by phasmal (2013-01-03 01:25:59+00:00)
Title: Added support for @see tag in markdown plugin

This is a bit of a bug/feature hybrid (no issue lodged). Currently the markdown plugin doesn't work properly if you add a '@see' tag in the list of enabled tags in the config (as described in the [docs describing the Markdown Plugin](http://usejsdoc.org/plugins-markdown.html)), since it'll mangle the tag text even if it doens't contain any markdown syntax (it wraps the text in html <p/> tags). This means that if you enable @see markdown conversion, @see tags that don't contain markdown will not function properly.

I figure the see tag ought to only do a conversion if a link is present (text contains '[' character is the test I used)

Some issues with this are:

- If there are any ways that Markdown allows links with some other form
- If there are any ways that jsdoc can legitimately use a '[' in a @see tag

If either of these issues are valid, then this change will cause plugin to fail to act sensibly in the respective cases.

However the alternative would be doing a full pattern match to ensure only a link is present (or does the markdown parser have functionality that can be interrogated to determine this?) and I thought this would be overkill in the situation.

So I implemented the following in this change:

- Added support for @see tag since it needs to only be converted if there is a markdown link present - indicated by presence of a '[' (and doesn't otherwise since it would stuff up the normal referencing behavior).

- Added @see (as 'see') to list of default tags for the markdown plugin (actually did this because I couldn't work out an easy way to test the feature without it - couldn't work out how to modify the config prior to the plugin being loaded in an isolated way)

- Added markdown plugin tests testing @see functionality to the markdown.js test file

**Note** that I also fixed a bug as part of this - it's necessary for this feature, but even irrespective of it would warrant fixing:

- Also fixed a recursion issue when process() in the plugin encountered an Array instance - it was recursing, but only passing the value, and the inner process() would ignore the value because it wasn't an object with properties present.
Modified this to send a 'fake' object to the inner process(), unwrapping and re-assigning the result afterwards.

In addition to the unit tests above, I've also used this change on my own codebase successfully.