Standardize callback/function parameter documentation

[mramato]

There are many places in Cesium where we either take a function as a parameter or property but fail to properly document what the signature of that function is. Most places have a textual description, (i.e. a callback that takes a date and value as a parameter) but we can surely do better than that.

I'm not sure that JSDoc has built in support, but I couldn't find any. I think the best solution is to define the callback in a standalone file (or all callbacks in a single file?) and document them there. Then the parameter or type of property is a link to that function in the documentation. This would go a long way to improving our documentation.

Thoughts?

[mramato]

We could also have each declared and documented at the top of the file of the object that uses it.

[shunter]

Haven't tried it, but http://usejsdoc.org/tags-callback.html looks appropriate.

[mramato]

I had found that, but couldn't get it to work. I just found both jsdoc/jsdoc#356 and jsdoc/jsdoc#260 though so I'll see if I can get them working. We are really far behind JSDoc versions, so that may be the problem as well. @kristiancalhoun how hard is it to update to a new JSDoc?

[J7mbo]

Do we really not have a {callable} yet?

[mramato]

Now that @shunter upgraded jsdoc, we've started using the callback notation linked to above. See Core/EasingFunction.js as an example. We need to search the code for {Function} and replace them all with documented callbacks. There's about 60 of them, but some of them may share the same callback definition.

[pjcozzi]

Could be fun for someone at the bug bash tomorrow. :)