Three.js: Question About Method Return Values in Documentation

[lejeunerenard]

I've been looking at contributing documentation changes and noticed that there are some inconsistencies with the return value of methods.

For example, Vector3's page has a this after all methods that modify the Vector3 in place and then return the same Vector3. But there are methods like .distanceToSquared() that have no return value after the method.

So my questions are:

1. When should a return value follow a method definition?
2. When should that return value text be this or the type, eg. Vector3?

_Side Note:_ There are methods that link to non-existent pages because their return type is a standard JS type ( eg. Boolean, Float, etc ). This is confusing if you are expecting to be redirected to the page on that type.

[Mugen87]

Yes, the docs are somewhat inconsistent from this point of view.

When should a return value follow a method definition?

Always when a method actually returns a value via return.

When should that return value text be this or the type, eg. Vector3?

Because we don't explicitly mention the type, it's better to just use the name of the return value like this, distance or length. Type information is embedded in the respective link.

There are methods that link to non-existent pages because their return type is a standard JS type ( eg. Boolean, Float, etc ).

I think the easiest way to solve this problem is to create pages for these types. Other suggestions?

[looeee]

All the 'this' after all methods has been removed from the documentation - it was very unclear that it meant a return type, was only added for a few methods throughout the documentation, and also the return type of each function is given in the "non-existent pages" (or sometimes existent pages!).

I agree that a better method of describing return types is needed - I think this can be done automatically, as all methods are described in the docs like:

<h3>[method:Material copy]( [page:material material] )</h3>
<div>
     //optional argument details here <br><br>

    //description here
</div>

The 'method:Material' means that the above method returns a Material.

So some regex can pick out a method definition and return type... but then what?

[mrdoob]

How about...

<h3>[method:Material copy]( [page:material material] )</h3>
<div>
     //optional argument details here <br><br>

    //description here

    Returns `undefined`.
</div>

Also, maybe self is better than this?

[looeee]

Saying that the method is chainable would be better than either - or maybe 'returns self (chainable)'.

[mrdoob]

Hmm, I find confusing to say it is chainable. I think the fact that is chainable is a "side effect" of returning self.

[looeee]

I was under the impression that side effect is the reason for returning self. Is there any other reason?

[WestLangley]

I think the fact that it is chainable is a "side effect" of returning self.

I think we return self so that it is chainable.

All the 'this' after all methods has been removed from the documentation

Good.

I agree with what @mrdoob said: Just say:

Returns undefined/self/this

[looeee]

Just say: Returns undefined/self/this

OK, that will make things simpler to add anyway

[lejeunerenard]

Closing as this is out of date.

All this references have been replaced with just the type of the returned value. And all standard JS types are no longer links.