Greater granularity in specification of value types

[GoogleCodeExporter]

I'd like the ability to specify (multiple) return or parameters which
describe a value in a special way (e.g., @param {Boolean:true} ... or
@returns {Boolean:true} ...) where the ellipsis contains a description
specific to that value.

In some functions, the meaning of the boolean is not a clear cut case of
"do something or not". For example, the functioning returning true, giving
a string, undefined, etc. could indicate one thing, while false implies the
handler sequence should abort. Being able to specify these on separate
lines and in a formal way could I think make the code clearer.

Original issue reported on code.google.com by bret...@gmail.com on 25 Aug 2009 at 9:53

[GoogleCodeExporter]

It is already possible to document multiple @params and @returns, so I'm not 
clear what case would be the 
problem for you. Can you give a more complete example of what you would like to 
do?

One possible answer to the question I'm not clear on might be like this:

/**
 Set a property.
 @param {Boolean} strict Parse the text using strict rules or not.
 <dl>
    <dt>true</dt><dd>Error will be thrown when missing tags are found.</dd>
    <dt>false</dt><dd>Missing tags are simnply ignored.</dd>
 </dl>
 @returns {Boolean} The result of the parse.
 <dl>
    <dt>true</dt><dd>The parse attempt was successful.</dd>
    <dt>false</dt><dd>The parse attempt failed.</dd>
 </dl>
 */

Does that help?

Original comment by micmath on 12 Sep 2009 at 6:23

• Changed state: MoreInfoRequired

[GoogleCodeExporter]

Yes, that is exactly what I needed... Maybe this convention could be spelled 
out on
the wiki as well? (I see the wiki is not publicly editable)...

Original comment by bret...@gmail.com on 13 Sep 2009 at 11:21

[GoogleCodeExporter]

Yeah, I agree that better documentation would be nice, then, as I also had no 
idea 
you could do that.  That will come in handy, though!

Original comment by james.m....@gmail.com on 14 Sep 2009 at 7:58