Support document updates

[GoogleCodeExporter]

The problem:
Some changes can not be documented (* unless using custom means). For 
example, changing a function signature. If you add a new parameter to the 
function signature, you can't use the @since tag to document the version 
when this parameter was introduced. The same goes for exceptions (@throws).

This is especially important if you are planning to create a changeLog or 
a "what's-new" section in your document.

The proposed solution:

Allow updates - instead of rewrting the entire doclet, just add/update the 
changes:

/**
 * @function
 * @name foo
 * @since 1.0
 * @param {String} bar1
 * @param {String} bar2
 * @throws exception1
 */

/**
 * @function
 * @name foo
 * @since 2.0
 * @param {Number} bar3
 * @throws exception2
 */

The output should be a function named "foo" with 3 parameters (bar1, bar2, 
bar3) and 2 exceptions (exception1, exception2).
Also, @since should effect the entire doclet, but should not update the 
function itself.

The current implementation overwrites the entire function resulting with a 
function named "foo" with 1 parameter (bar3) and 1 exception (exception2).

* It is fairly easy to create your own tags (like @chaneLog), but I think 
this feature is too improtant to be left for customization.

THIS FEATURE WILL NOT BE IMPLEMENTED UNLESS A LARGE NUMBER OF USERS WILL 
SUPPORT IT, SO PLEASE ADD YOUR COMMENTS.

Original issue reported on code.google.com by herz...@gmail.com on 25 Oct 2008 at 10:59

[GoogleCodeExporter]

This isn't a popularity contest. Begging large numbers of people to add 
comments here so you can get your feature 
is not useful: please don't do that.

In my last email to you I suggested you post your proposal on the mailing list 
(it's at http://groups.google.com/group/jsdoc-2 ) and see how many people agree 
that it is needed. I still think you should 
do that. The point would be to get an honest reaction from actual users. I 
would consider it a biased response if you 
add any all-caps messages that you desperately need people to help you out by 
responding with comments. If the 
proposal isn't interesting on its merits then yelling about won't make it any 
more useful to users.

Original comment by micmath on 27 Oct 2008 at 11:48

• Changed title: Support document updates
• Changed state: MoreInfoRequired
• Added labels: Priority-Low, Type-Enhancement
• Removed labels: Priority-Medium, Type-Defect

[GoogleCodeExporter]

Original comment by micmath on 21 Jun 2009 at 10:50

• Changed state: WontFix