Can't document methods when using className.prototype.method=function() {} pattern

[GoogleCodeExporter]

What steps will reproduce the problem?
Create the following code:

<code>
function myClass() {
  this.value = 'that';
  // etc.
  return this;
}

myClass.prototype.myMethod = function() {
  // function body
}
</code>

What is the expected output? What do you see instead?

Have searched through the "Issues" section, and tried lots of different
combinations of @constructor, @class, @function, @memberOf, @lends, etc -
but have not been able to come up with a solution that documents (a) the
class myClass, or (b) the method myMethod.

What version of the product are you using? On what operating system?
JSDoc: jsdoc_toolkit-2.1.0
OS: SunOS 5.10 i86pc

Please provide any additional information below.

Have done my best to research before posting - so apologies in advance if
this problem has already been solved!

Original issue reported on code.google.com by mcalth...@gmail.com on 24 Feb 2009 at 5:10

[GoogleCodeExporter]

It may be obvious to you (and I) that myClass is a "class" but JsDoc Toolkit 
can't tell if it's meant to be called 
as simple function or if it's meant to called with the "new" keyword unless you 
tell it so. Use the @class tag or 
the @constructor tag.

(using the -a option)

/** @class */
function myClass() {
 this.value = 'that';
 // etc.
 return this;
}

myClass.prototype.myMethod = function() {
 // function body
}

Original comment by micmath on 24 Feb 2009 at 6:11

• Changed state: Invalid

[GoogleCodeExporter]

Thanks Michael!

Had already tried that - but I can't remember if I used the -a option - will 
check 
when I'm back at work tomorrow.

Matt

Original comment by mcalth...@gmail.com on 24 Feb 2009 at 9:11

[GoogleCodeExporter]

The -a option just means "document (a)ll functions, even those that have no 
doc-comments attached to 
them." As you have no doc-comment for myClass.prototype.myMethod, you will need 
to use the -a option to 
get it to appear in your output. However, you may omit the -a if you provide a 
comment, like so:

/** @class */
function myClass() {
 this.value = 'that';
 // etc.
 return this;
}

/** This is just an example method. */
myClass.prototype.myMethod = function() {
 // function body
}

Original comment by micmath on 25 Feb 2009 at 9:32

[GoogleCodeExporter]

Ok, I'm getting closer...

When I test this code in isolation, it works as expected:

/** @class */
function myClass() {
    this.value = 'that';
    // etc.
    return this;
}

/** this is myMethod */
myClass.prototype.myMethod = function() {
    // function body
}

However, when I test it as part of a much larger suite of code, I get a lot of
warning messages for the other files, and here are the messages I get for the 
myClass
file:

>> WARNING: Trying to document myClass as a member of undocumented symbol 
IPC.Dialog#.
>> WARNING: Trying to document myMethod as a member of undocumented symbol 
myClass.

IPC.Dialog is a class that has been defined in another file.

So is the context somehow being messed up?

And if so, is there a way of resetting it?

many thanks,

Matt

Original comment by mcalth...@gmail.com on 25 Feb 2009 at 9:47

[GoogleCodeExporter]

Ah - finally found the solution:

/** @scope global */
/** @class */
function myClass() {
    this.value = 'that';
    // etc.
    return this;
}

myClass.prototype.myMethod = function() {
    // function body
}

I don't even need a comment above myMethod for it to be picked up.

Also: don't combine the two JSDoc comments into one - JSDoc won't pick up the 
code.

Original comment by mcalth...@gmail.com on 11 Mar 2009 at 3:57

[GoogleCodeExporter]

oops - that first line of code should have read:

/** @scope _global_ */

(underscore before & after "global")

Matt

Original comment by mcalth...@gmail.com on 12 Mar 2009 at 11:32

[GoogleCodeExporter]

That's pretty clever, I never would have thought to do that actually!

Original comment by micmath on 19 Mar 2009 at 9:58

[GoogleCodeExporter]

It took lots of experimentation!

Original comment by mcalth...@gmail.com on 19 Mar 2009 at 10:23