How to document code in "closures"
julien
I have this code :
/**
* @fileOverview This file has functions related to documenting
JavaScript.
* @author <a href="mailto:"></a>
* @version 1.0.1
*/
/** namespace */
(function() {
/**
* The constructor for our test class
* @class Represents a Test
*/
function Test(name) {
this.setName(name);
}
/**
* Returns this test's name
* @scope Test
* @return String
*/
Test.prototype.doSomething() {
return this.name;
};
/**
* Sets this test's name
* @param String the name we want to use for this test
*/
Test.prototype.setName(name) {
this.name = name;
}
})();
When I run js-toolkit no comments are shown, could you please help?
Thanks
Michael Mathews
The problem is that, if this code were run exactly as you've written it, there would be no API created. Which is why there are no API docs generated actually. That's because your constructor is not visible outside of the wrapping anonymous function. So empty docs is correct.
But I'm going to assume that you want your docs to be different than your code, and even though the Test function is not visible outside of the anonymous function, you want it documented as if it were available globally. The problem then becomes how do you tell JSDoc that you want it to be documented as something it isn't.
This is simpler in JSDoc 3, but in JSDoc toolkit, it means you have to add @name tags to pretty much everything you wish to rename, like so...
```javascript
/**
* @fileOverview This file has functions related to documenting JavaScript.
* @author <a href="mailto:"></a>
* @version 1.0.1
*/
(function() {
/**
* The constructor for our test class
* @class Represents a Test
* @name Test
*/
function Test(name) {
/** @name Test#name */
this.name = name;
}
/**
* Returns this test's name
* @return String
* @memberof Test#
*/
Test.prototype.getName = function() {
return this.name;
};
})();
```
Michael Mathews
mic...@gmail.com
> --
> You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
> To post to this group, send email to jsdoc...@googlegroups.com.
> To unsubscribe from this group, send email to jsdoc-users...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/jsdoc-users?hl=en.
>
theallan
JSDoc3? Simpler works for me!
If I add the name to the top level class, then it isn't propagated
automatically to the other hidden properties etc, it looks like I need
to add the name to everything as well. Is that the case?
Thanks,
Allan
Michael Mathews
Can I first ask you to provide a better illustration of what you want to achieve? The original example isn't realistic, because there isn't a usecase for documenting an inner function as if it were really a global. Can give a minimal example of the kind of code you want to document, and some explanation of what you expect the docs to show?
Michael Mathews
mic...@gmail.com
Terry Weiss
to add window.myObj = new Test(); just before the end of the closure?
Michael Mathews
Terry Weiss
/**
@global
@name myObj
@type {Test}
*/
window.myObj = new Test() ;
The result would be that in global, you'd get myObj showing up. I'd want
to click through the type to see what the runtime object contains.
Michael Mathews
Without the anonymous function wrapping your code, you'd write this:
```
/**
This is an example.
@constructor
@private
*/
function Thing(name) {
/** Describe me. */
this.name = name;
}
/**
Set the isHungry state.
@param {boolean} hungry
*/
Thing.prototype.setHungry = function(hungry) {
/** Describe me. */
this.isHungry = hungry;
};
/**
@var {Thing} myObj
*/
window.myObj = new Thing();
```
With the anonymous function the `Thing` constructor cannot be seen from outside its enclosing function, and so it is documented as an inner member of <anonymous>, which it is, but that means it can't appear in the output docs. You can force all your docs inside the anonymous function to appear as if they were attached to global symbols by adding 1 extra tag:
```
(/** @lends <global> */function() {
/**
This is an example.
@constructor
@private
*/
function Thing(name) {
/** Describe me. */
this.name = name;
}
/**
Set the isHungry state.
@param {boolean} hungry
*/
Thing.prototype.setHungry = function(hungry) {
/** Describe me. */
this.isHungry = hungry;
};
/**
@var {Thing} myObj
*/
window.myObj = new Thing();
})();
```
Or, if you wanted only one Thing to be documented as if it were a global, you could do something like this:
```
(function() {
/**
This is an example class
@class
@private
@global
*/
function Thing(name) {
/** Describe me. */
this.name = name;
}
/**
Set the isHungry state
@memberof Thing
@param {boolean} hungry
*/
Thing.prototype.setHungry = function(hungry) {
/** Describe me. */
this.isHungry = hungry;
};
/**
@var {Thing} myObj
*/
window.myObj = new Thing();
})();
```
Michael Mathews
mic...@gmail.com
Terry Weiss
theallan
Thanks very much for the suggestions. This is the file that I am
looking to document: https://github.com/DataTables/DataTables/blob/1_9_DEV/media/src/DataTables.js
(that's the reduced version - with the require() "include files" -
when fully expanded it looks like this:
https://github.com/DataTables/DataTables/blob/1_9_DEV/media/js/jquery.dataTables.js
.
So basically I've got the DataTable variable as a local variable, that
then gets aliased to a jQuery namespace, which is how it is made
publicly accessible. I could document it as attached to that jQuery
namespace, possibly that is the correct thing to do, but I had been
thinking of documenting it just locally, to make the documentation a
more direct reference to the implementation.
I've just tried adding the @lends <global> to the closure function and
it almost does what I was looking for, but the API methods that are on
the DataTable object are put into the global space, rather than
attached to the object.
Thanks again,
Allan
>
> On 6 Dec 2011, at 21:33, Terry Weiss wrote:
>
>
>
>
>
>
>
> > Try this:
> > /**
>
> > @global
> > @name myObj
> > @type {Test}
> > */
> > window.myObj = new Test() ;
>
> > The result would be that in global, you'd get myObj showing up. I'd want to click through the type to see what the runtime object contains.
>
> > On 12/06/11 16:29, Michael Mathews wrote:
> >> And you are documenting "myObj"? What you expect the docs to show?
>
> >> On 6 Dec 2011, at 21:15, Terry Weiss wrote:
>
> >>> What would your response had been if the only change to the original was to add window.myObj = new Test(); just before the end of the closure?
>
> >>> On 12/06/11 15:15, Michael Mathews wrote:
>
> >>>> Hi Allen,
>
> >>>> Can I first ask you to provide a better illustration of what you want to achieve? The original example isn't realistic, because there isn't a usecase for documenting an inner function as if it were really a global. Can give a minimal example of the kind of code you want to document, and some explanation of what you expect the docs to show?
>
> >>>> Michael Mathews
> >>>> micm...@gmail.com
>
> >>> --
> >>> You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
> >>> To post to this group, send email to jsdoc...@googlegroups.com.
> >>> To unsubscribe from this group, send email to jsdoc-users...@googlegroups.com.
> >>> For more options, visit this group athttp://groups.google.com/group/jsdoc-users?hl=en.
Michael Mathews
I only looked at the reduced version. I would document it something like this: https://gist.github.com/1449056
If, using this pattern, you have a case where a method is appearing as global, try adding a `@memberof DataTable` tag. Let me know if that doesn't answer your question.
Michael Mathews
mic...@gmail.com
theallan
That's absolutely fantastic - thanks very much! Documents DataTables
absolutely spot on how I had hoped :-)
Regards,
Allan
On Dec 8, 10:49 pm, Michael Mathews <micm...@gmail.com> wrote:
> Hi Allen,
>
> I only looked at the reduced version. I would document it something like this:https://gist.github.com/1449056
>
> If, using this pattern, you have a case where a method is appearing as global, try adding a `@memberof DataTable` tag. Let me know if that doesn't answer your question.
>
> Michael Mathews
>
> On 7 Dec 2011, at 09:13, theallan wrote:
>
>
>
>
>
>
>
> > Hi Michael,
>
> > Thanks very much for the suggestions. This is the file that I am
> > looking to document:https://github.com/DataTables/DataTables/blob/1_9_DEV/media/src/DataT...
> > (that's the reduced version - with the require() "include files" -
> > when fully expanded it looks like this:
> >https://github.com/DataTables/DataTables/blob/1_9_DEV/media/js/jquery...