search

AaronNGray / jsdoc-toolkit

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

What do I use a tag in overloaded function? #276

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
Hello~
I'm javascript developer in Korea.
I developed overloaded function in javascript class..
Class constructor overloaded or normal method overloaded..

What types of tag do I use in this situation?

Original issue reported on code.google.com by Boxe...@gmail.com on 5 Jan 2010 at 4:26

GoogleCodeExporter commented 9 years ago 
Can you give a short, simple example of your overloaded functions?

Original comment by micmath on 5 Jan 2010 at 7:16

GoogleCodeExporter commented 9 years ago 
This is a simple Example.
DCircle class used in map application.
------------------
var DCircle = function(spoint, epoint, options){
   ....
   this.sPoint = spoint;

   if(epoint instanceof DPoint){ //When epoint is instance of DPoint Class
      this.drawMode = "Oval";
      this.epoint = epoint;
   }else{ // When epoint is not instance of DPoint Class, probably.. it is Number 
variable
      this.drawMode = "Radius";
      this.point = this.sPoint;
      this.radius = epoint;
   }
};
...
--------------------
DCircle Class has 3 arguments. (spoint, epoint, options)
spoint and epoint is normally Instance of "DPoint".
DPoint class abstracts coordinate type class.
In this case, DCircle class draws an scaleable circle in the Map.
(drawMode = "Oval")

but. In different ways..
'spoint' is Instance of DPoint. and 'epoint' is Not Instance of DPoint.
Probably epoint has 'Number' type variable.
In this case, DCircle class draws an absolute radius circle in the Map.
(drawMode = "Radius")

so ugly english.. I'm sorry..

Thank you.

Original comment by Boxe...@gmail.com on 5 Jan 2010 at 7:48

GoogleCodeExporter commented 9 years ago 
Okay, I think I understand. This is a very common pattern to follow in 
JavaScript. There are a couple of ways to solve 
your documentation problem.

The first is quite straightforward: just explain your interface:

/**
    @param {arguments} ... This function can be called in the following ways:
    <dl>
        <dt>setProp(name, value)</dt>
        <dd>
            name: The name of the property, as a string.<br />
            value: The value to set it to.<br />
        </dd>
        <dt>setProp(nameValues)</dt>
        <dd>
            nameValues: A collection of name/value pairs, as an object.
        </dd>
    </dl>
    @example
        setProp('size', 7);
        // or
        setProp({'size': 7, 'color': red});
 */
var setProp = function() {
    // normalize input
    if (arguments.length === 1) {
        nameValues = arguments[0];
    }
    else if (arguments.length === 2) {
        nameValues = {arguments[0], arguments[1]};
    }
    else {
        throw new Error('Invalid signature, see usage notes.');
    }

    // do something with the nameValues input
}

That might seem a little inelegant, and I suppose it is but remember that 
documentation is a form of communication. 
As long as your message is easily understood you have produced good 
documentation. However if you want a slightly 
more clever solution there is a little known feature of the standard JsDoc 
Toolkit template that lets you document 
multiple functions or methods with the same name. In this case you might want 
to document each variation of your 
overloaded function separately. The secret is you just add a @name tag to you 
doc comment, and append a "^2",  "^3" 
(and so on) to the names of the overloaded forms. Like this:

/**
    @name init
    @function
    @param {string} key
    @param {mixed} value
 */
 /**
    @name init^2
    @function
    @param {object} keyValues
 */
var init = function() {
    if (typeof arguments[0] === 'string' && arguments.length === 2) {
        // signature 1 ...
    }
    else if (typeof arguments[0] === 'object') {
        // signature 2 ...
    }
    else {
        throw new Error('Invalid signature, see usage notes.');
    }
}

Original comment by micmath on 5 Jan 2010 at 3:28

GoogleCodeExporter commented 9 years ago 
I'll update my jsdoc template for ^2, ^3 convention.
Thank you very much.. :)

Have a nice day~~ ^^

Original comment by Boxe...@gmail.com on 6 Jan 2010 at 2:30