search

swallowzhang / jsdoc-toolkit

Automatically exported from code.google.com/p/jsdoc-toolkit
0 stars 0 forks source link

@warning/@pitfall/etc. #240

Closed GoogleCodeExporter closed 8 years ago

GoogleCodeExporter commented 8 years ago 
I feel like it would be helpful to have a tag like @caution or @warning
indicating particular usage concerns beyond those which fit in a
description, example, or indication of deprecation. 

@note may be more useful in being more generic (e.g., for notes on usage
which were not "dangerous" in some way but which still drew the attention
of the user to some of the item's non-intuitive aspects, but I believe such
a tag could really be abused as a catch-all. I guess @pitfall might be
better for this as it is often used for less serious items.

So maybe both @warning and @pitfall could suit both cases--where @warning
was for more serious issues and @pitfall for noting some non-intuitive
usage issues.

Perhaps even better might be just one tag to avoid confusion (I think
@pitfall could encompass both severe and less severe types), but allow an
optional severity level to be added

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

GoogleCodeExporter commented 8 years ago

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

GoogleCodeExporter commented 8 years ago 
I would like at least the "@note" tag, but I do see value in having the 
"@warning"
and "@pitfall" as well.  Not positive that "@pitfall" makes that much sense... 
seems
like your code shouldn't be THAT dangerous and that a "@warning" should cover
anything dangerous.

My vote would be for just @note and @warning.

Original comment by james.m....@gmail.com on 25 Sep 2009 at 1:58

GoogleCodeExporter commented 8 years ago 
This can already be accomplished using the custom tag feature in JSDoc 2.

http://code.google.com/p/jsdoc-toolkit/wiki/FAQ#Using_custom_tags

Original comment by micmath on 3 Jul 2010 at 8:05