documentation of getter / setter

[Julien Iguchi-Cartigny]

Hi,

I'm trying to document a setter / getter using new syntax to define
them with javascript 1.5, but It didn't work (the get / set functions
don't appear in the generated documentation). Is it a special way to
use jsdoc -toolkit to make them appear in the documentation ?

This my source code with documentation, neither get category() and set
category(c) appear:

/**
* Creates a new Tag instance
*
* @class The Tag class
* @constructor
* @public
* @param {String} name The name of the tag
*/
function Tag(name) {

/**
* The name of this tag
*
* @public
* @type String
*/
this.name = name;

/**
* The category where the tag belong
*
* @private
* @type Category
*/
this._category = null;
}

Tag.prototype = {

/**
* Getter for category. This function exists to forbid access to
* #category if no save has been done.
*
* @public
* @throws Error if the tag instance has not been saved
*/
get category() {
if(typeof(this.id) === "undefined") {
throw new Error("save Tag before get category property");
}
return this._category;
},

/**
* Setter for category property. This function exists to forbid
access to
* #category if no save has been done.
*
* @public
* @param {Category} c the category set for the tag
* @throws Error if the tag instance has not been saved
*/
set category(c) {
if(typeof(this.id) === "undefined") {
throw new Error("save Tag before set category property");
}
return this._category = c;
}
};

Cheers,

Julien.

[Julien Iguchi-Cartigny]

Hello again,

I've patch my jsdoc-toolkit install with the getter/setter patch found
here:

<http://code.google.com/p/jsdoc-toolkit/issues/detail?id=169>

But you have still some problems (with the same code posted in my
previous email):

- the setter is parsed as a variable, so the text of the field is the
setter description
- there is no mention of the getter

This is not convenient for me: I want to see the getter / setter
methods.

Any proposition to update this code ?

Cheers,

Julien.

[Michael Mathews]

Hi Julien,

Sorry for my late response. I am trying to catch up but life seems to
keep speeding up!

I've had a think about your question and proposal, but I don't want to
add set and get support into the core of JsDoc Toolkit yet. There are
still options for you. Firstly, you can accomplish pretty much
anything by simply turning off the static code analysis feature of
JsDoc Toolkit, see the link below (you can skip right to the "but wait
there's more" section if you want).

http://code.google.com/p/jsdoc-toolkit/wiki/FAQ#How_to_get_JsDoc_Toolkit_to_work_with_my_code

Another option, or an additional option if you wish to combine the two
techniques, is to use labelled symbols. This is how I was able to add
support for functions that were really events into JsDoc Toolkit.
Basically you add a `@name label:symbolName` to your docs and then in
your template you can present that name however you wish, removing the
'label:' perhaps, or whatever else you like. In your case you could do
this:

Tag.prototype = {

/**
* Getter for category. This function exists to forbid access to
* #category if no save has been done

* @name Tag#get:category
* @function.

* @throws Error if the tag instance has not been saved
*/
get category() {
if(typeof(this.id) === "undefined") {
throw new Error("save Tag before get category property");
}
return this._category;
},

/**
* Setter for category property. This function exists to forbid access to
* #category if no save has been done.

* @name Tag#set:category
* @function

* @param {Category} c the category set for the tag
* @throws Error if the tag instance has not been saved
*/
set category(c) {
if(typeof(this.id) === "undefined") {
throw new Error("save Tag before set category property");
}
return this._category = c;
}
};

I'll leave it to you to modify the template to show that in a way you
like, but if you need help with that let me know.

Regards,
Michael