nevir/groc — pull request #96 by sjorek (2013-08-25 09:11:13+00:00)
Title: Multiline-descriptions for “@param”, “@return(s)” and “@throws” jsdoc-tags don't work

Hi everybody,

first of all - thanks for your hard work so far :+1:

The regular-expresions for “@param”, “@return(s)” and “@throws” jsdoc-tags in `lib/doc_tags.coffee` have been bound to a single line description:

parts = value.match /^…$/

Therefore multiline-descriptions break the process and throw an exception, as multiline-input does not match and returns **null**.

An example I stumbled upon (the `template`-method-paramter's description):

##
# HTML template processor. … (shortened a bit)
#
# @param {Context} context Context created from the input data object.
# @param {Element} template DOM node of the template. This will be processed
# in place. After processing, it will still be a
# valid template that, if processed again with the
# same data, it will remain unchanged.
# @param {Object} options Options passed to `Processor.create()`.
# @return {void}
process: (context, template, options) ->
…

My solution to make this work is trivial:

parts = value.replace(/\s+/g, ' ').match /^…$/

In my setup it does not break anything and there seems to be no objection to go this way.

What do you think ? I'd like to use multiline-descriptions and would be glad if you pull my (a little bit polished) solution or give me a hint, what alternatives I might have missed.