documenting different function signatures in JS

[Michael]

Hello,

There is an issue in the tracker concerning how to document a function
that can take different parameters and would then do different things
(give it one param and it does A, give it two and it does B).

See:
http://code.google.com/p/jsdoc-toolkit/issues/detail?id=75

Unofficially JsDoc Toolkit 1.x supports multiple doclets with the same
name, so you could (but probably shouldn't) document the same named
code twice (see the issue linked above for an example of how), once
for each variation.

JsDoc Toolkit 2 doesn't support this, but I'd like to have a more
obvious way to document the multiple-uses situation. I'm considering
the following syntax with a new @alt tag, and would like your
feedback. Other possiblitities: @also, @or, ...?

/**
* @param {string} fullname Fullname.
*/
foo = function(){
// code doing different things given nature of function arguments
}

/**
* @alt foo
* @param {string} firstname Firstname.
* @param {string} lastname Lastname.
*/

The alternative documentations would appear as additional
documentation chunks under the "real" documentation and would limited
to a description, @params, and @type.

Your thoughts?

Regards,
Michael

[TJ Rothwell]

Questions that I see

For each parameter signature, should the documentation allow:
1) @return - different returns
2) description
3) @config - the param is an object
4) all signatures to be placed in primary doclet - or as additional doclets /** <doclet> */

On the subject of alternative parameters:

Since you can also call a function by it's parameter names, I'm wondering if this could somehow include that.  Because you could do this polymorphic design a different way.

function foo(param1AsInt, param2AsInt, param3AsInt, param1AsStr, param2AsStr, param3AsStr) {}
foo(param1AsInt:1, param2AsStr:"2", param3AsInt:3);
foo(1, undefined, 3, undefined, "2", undefined);

-- TJ

[pedrosi...@gmail.com]

Dear Michael,

I was using a similar aproach than the following link to obtain
different function signatures:
http://code.google.com/p/jsdoc-toolkit/issues/detail?id=75

The only problem of this approach is that only one method will be
linkable, because the template uses the method name as a fragment of
url, as #methodName, so all signatures will be linking to the same
"#methodName". I've changed the "sweet" template to generate the
fragment including the full signature, so each method will point to a
different fragment, like:

methodName(param1) links to "#methodName(param1)"
methodName(param1, param2) links to "#methodName(param1,param2)"

And making this, everything works fine.

I've tried downloading the last revision from version 2.0, and I've
noticed that this approach isn't working anymore, because as you
pointed at the above link, the version 2.0 "is
implemented such that only one doclet can be associated with any given
name".

I think a good workaround for this problem is to use a full method
signature as the "name" which will be stored at the symbols
collection. Then, differents signatures will have uniquely "names".
The generated URL for all methods will include parenthesis and
parameters name, but I don't see this as a problem. In fact, I think
is also good to readability, because when you see the "#methodName()"
in the end of the URL you know that is about a method, and not a
property.

I hope you find this idea useful.

Keep going with this fantastic work!

regards,

Pedro Simonetti Garcia.

[Michael Mathews]

Hello Pedro,

I see that your proposal would work, but I'm not sure how popular it
will be to require people to share links with the entire parameter
list included. This would also have to be applied to constructors
too, so Class#constructor(param1) and Class#constructor(param1,param2)

I'd like to postpone the release of Version 2 a little in order to
consider this, because it changes the usage of the documentation in
such a visible way.

Would you please file this as an requested feature in the tracker?

Best Regards,
Michael

[pedrosi...@gmail.com]

Michael,

Thanks for your response and considerations, I will post in the
feature request list.

I think maybe will be useful to share a little workaround to define
different signatures documentations, but this only works to version
1.4.x. This isn't working at version 2.0.

The solution is to use the "²" e "³" chars after the method name. This
way you can document up to 3 different signatures, like:

/**
* Main signature
* @name method
* ...
*/

/**
* Second signature
* @name method²
* ...
*/

/**
* Third signature
* @name method³
* ...
*/

Okay, this is a bit ugly, but maybe someone find this useful! =)


my best regards,

Pedro.

On 25 fev, 04:18, Michael Mathews <micm...@gmail.com> wrote:
> Hello Pedro,
>
> I see that your proposal would work, but I'm not sure how popular it
> will be to require people to share links with the entire parameter
> list included. This would also have to be applied to constructors
> too, so Class#constructor(param1) and Class#constructor(param1,param2)
>
> I'd like to postpone the release of Version 2 a little in order to
> consider this, because it changes the usage of the documentation in
> such a visible way.
>
> Would you please file this as an requested feature in the tracker?
>
> Best Regards,
> Michael
>

[Michael Mathews]

I quite like that actually! I'll have a think about getting it to work in Version 2.

Regards,
Michael

[pedrosi...@gmail.com]

Hey Michael,

I saw you just published the version 2.0 preview 2. Is this include
the different function signatures issue?

By the way, I'm downloading and testing this new preview.

Thanks!

Pedro.

On 26 fev, 11:04, "Michael Mathews" <micm...@gmail.com> wrote:
> I quite like that actually! I'll have a think about getting it to work in
> Version 2.
>
> Regards,
> Michael
>

[Michael Mathews]

Hi Pedro,

The last release was focused on fixing important bugs; adding new
features will happen in later releases. You can track the progress of
your issue in the project issue tracker (yours is #87).

Thanks for testing 2.p2 for me. Everyone's feedback has been
extremely helpful so far.

Regards,
Michael

[pedrosi...@gmail.com]

No problem Michael,

By the way, I was about to offering you some help in this issue, if
you like, of course. I didn't fully understood the JsDocToolkit core
yet, but with some directions from you I can experiment some
implementations.

In a earlier experiment, I've noted that putting the following code in
the beginning of JSDOC.Symbol.init will put the method signature in
the symbol name property.

---------------------------------------
this.init = function(
/** String */ name,
/** Object[] */ params,
/** String */ isa,
/** JSDOC.DocComment */ comment
) {

// Add the method signature to the symbol name property
if (isa == "FUNCTION") {
name += "(";
for (var i=0; p=params[i]; i++) {
name += (i>0 ? ",":"")+ p.name;
}
name += ")";
}
---------------------------------------

But, the name of functions declared as virtual objects won't be
properly changed. For example:

---------------------------------------
/**
* This is a function declared with a vitual object (@name)
*
* @name functionName
* @function
* @param {String} param
*/
---------------------------------------

I think, that changing all method names to include the signature, and
then changing the Link().toSymbol() function would solve this. But
since I didn't fully understood the core yet, I'm not sure if I'm
missing something.

my best regards,

Pedro.

On 13 mar, 05:11, Michael Mathews <micm...@gmail.com> wrote:
> Hi Pedro,
>
> The last release was focused on fixing important bugs; adding new
> features will happen in later releases. You can track the progress of
> your issue in the project issue tracker (yours is #87).
>
> Thanks for testing 2.p2 for me. Everyone's feedback has been
> extremely helpful so far.
>
> Regards,
> Michael
>