Allowing same name symbol

[GoogleCodeExporter]

In large web projects with many modules it makes sens that you encounter 
methods or functions with the same name that are in seperated files.

Jsdoc rejects same name symbols. I personaly think this is not the job of 
a documentation generator to do this but rather the job of a validation 
tool _if this is what is wanted for the project_.

Allowing same name symbol would be greatly appreciated for large projects 
where documentation makes more sens than small controlable projects.

Original issue reported on code.google.com by idef...@gmail.com on 7 Oct 2008 at 3:55

[GoogleCodeExporter]

Sorry, not possible. Just one example, if you define two Foo.Fidget() 
constructors in separate files, with 
different parameters and properties, which one would this refer to?

/**
    @class
    @extends Foo.Fidget
 */
function Foo.Figgle() { // extends which Foo.Fidget? There's no way to know.
}

If you define two different symbols with the same name you make it hard to 
document -- there's nothing I 
can do about that. You can always run jsdoc toolkit twice, once on the first 
set of files and then again on the 
second set.

Original comment by micmath on 7 Oct 2008 at 5:44

• Changed state: WontFix

[GoogleCodeExporter]

Thank you for responding. First I need to compliment you for your work.

I understand it is hard to realise but not impossible. Doxygene succeeds in 
managing 
php documentation where you encounter the very same type of problems. 

Again it is not the documentation tool that should tell the developper he must 
have 
only one single representation of a named symbol.

I can think of so many cases (seen and possible) in which you may have several 
same 
named symbols (especialy in javascript) that I do not concieve a web project 
documentation being truncated by such assomptions. This is not true for 
javascript 
frameworks, but it is in large (very large) web projects. We're talking about 
thousands of files, so more than only two possible cases.

In my point of view the class should always be documented. When encountering 
the 
extends problems and if it is too hard to implement for now, then, and only 
then 
(maybe %2 of the cases), a warning should be returned and the extended methods 
not 
be documented for this class. But overwritting every single symbols  is way to 
extremist.

- The best solution would be to adopt what doxygene does.
- The worst would be to at least tell which file causes the overwritting.
- An alternative solution would be an optional setting in the @extends that 
could 
help in telling the file it refers to in conflict cases.
/**
@class
@extends Foo.Fidget in fooIE.js
*/

Original comment by idef...@gmail.com on 9 Oct 2008 at 1:10

[GoogleCodeExporter]

@extends was just the first case that came to my mind, but there are lots of 
others.
Such as @link, @memberOf, @throws, @returns, @borrows, @lends...

One more example, what about the type in parameters?
@param {Foo.Fidget in fooIE.js | bar.Fidget in barIE.js} fidget

It would be a large increase in complexity for a (I assume) relatively small 
number
of users who would benefit.

Look, my documentation system is not telling you how to do anything. You paid 
zero
for my work same as everyone else. If you feel like your freedom is being 
restricted
the solution should be obvious (sorry but I think I might throw up if I ever 
hear
that particular argument used again).

Now, believe it or not, I totally agree with you. In fact, version 0.1 of JsDoc
Toolkit worked exactly this way: symbols were sorted by the file they were 
defined
in, so you were free to have the same named symbol in different files. But that 
was
before @extends and others were implemented when it became obvious that the work
required to support this feature was more than I wanted to invest.

JsDoc Toolkit was only ever scoped to be a replacement for my original project
written in Perl -- with some minor improvements. But importantly it's now 
written in
JavaScript for the simple reason that now any user can contribute. If you want 
this
feature I'd suggest two things: first post your proposal on the user's mailing 
list
and see what interest there is; second submit a patch to do some small part of 
what
you want (I'd like to see what big changes are required to get it to work).

Original comment by micmath on 14 Oct 2008 at 7:19

• Changed state: MoreInfoRequired
• Added labels: Type-Enhancement
• Removed labels: Type-Defect

[GoogleCodeExporter]

Original comment by micmath on 9 Jan 2009 at 11:30

• Changed state: WontFix