search

AaronNGray / jsdoc-toolkit

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

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

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
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 commented 9 years ago 
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

GoogleCodeExporter commented 9 years ago 
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 commented 9 years ago 
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 commented 9 years ago 
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 commented 9 years ago 
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 commented 9 years ago 
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 commented 9 years ago 
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 commented 9 years ago 
It took lots of experimentation!

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