Underscored functions should default to @private

[GoogleCodeExporter]

Currently all functions with documentation comments are printed to the
output, unless a @private tag is added. In general, the JavaScript
convention is to use an underscore character ("_") before any "private"
function or variable. This is also how JSDoc handles undocumented functions.

But when a documentation comment is present, all functions are by default
"public" which seems a bit backward. I think it would be better if those
functions defaulted to @private unless a @public tag was specified. That
way the properly commented code doesn't need to declare @private everywhere
but can instead rely on standard JavaScript conventions.

I know this is somewhat a matter of personal opinion, but default values
optimized for common usage patterns is a timesaver for everyone.

Original issue reported on code.google.com by cederb...@gmail.com on 28 Feb 2008 at 12:57

[GoogleCodeExporter]

BTW. This is related to #9.

Original comment by cederb...@gmail.com on 28 Feb 2008 at 1:00

[GoogleCodeExporter]

Are you saying you have an underscore-named function you don't want to appear 
in the
documentation? Use the -a option (instead of the -A option) and don't comment 
it with
a /** comment. Would that not accomplish what you want?

The @private tag is from the original JSDoc.pl project 
http://jsdoc.sourceforge.net/
so will be supported for historical reasons.

Original comment by micmath on 28 Feb 2008 at 7:44

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

[GoogleCodeExporter]

I want to retain the option of generating *both* internal and public 
documentation.
So I naturally comment all functions, whether private or public. Now I'm forced 
to
explicitly  add a "@private" to all comments for underscored functions, which 
seems a
bit excessive since they already have "private" names.

I'm not using either -a or -A options.

Original comment by cederb...@gmail.com on 14 Mar 2008 at 3:29

[GoogleCodeExporter]

Looking at this from the opposite direction: if underscored functions were 
always
automatically treated as if they had @private tags, how would some one indicate 
they
didn't want one to be private? That may be rare but they would have no option,
whereas by the current state of things, at least you would have the option of 
adding
a @private tag to underscored methods or not. I'd like to come up with a way 
that is
flexible and also convenient. It may be that Version 2 now allows a plugin to be
created to do this. Another option is to provide a commandline option to turn 
this
behavior on. I'll have a think about it, but feel free to make any suggestions.

Original comment by micmath on 15 Mar 2008 at 12:06

• Changed state: Accepted

[GoogleCodeExporter]

In issue #101 a new tag was added: @public, which allows your requested feature 
to be
usable. As of revision 546 underscored names are now automatically marked as 
private.
And you can cancel that by using the new @public tag.

Original comment by micmath on 23 Mar 2008 at 10:55

• Changed state: Fixed

[GoogleCodeExporter]

Would it be reasonable to add a command line option not to treat underscored 
functions as private? Many times 
underscored functions are used for obfuscation purposes, where this works 
incorrectly, marking all functions as 
private.

Original comment by dusan.smolnikar@gmail.com on 21 Jan 2010 at 10:35