Scrub reference doc

[pjcozzi]

Including filling in all DOC_TBA or marking them @private.

CC #1587

[shunter]

Remaining documentation items:

• To document options parameter objects correctly, the options parameter itself must be listed as a @param. CesiumWidget does it correctly, most other places do not. Addresses Reference doc makes constructor parameters unclear #1114.
• jsdoc does not deduce type of property from returns doc #1450. Properties must document their type with @type, not @returns.
• HTML in comments in code examples should not be escaped. See BaseLayerPicker for an example of the problem.
• @memberof may not be necessary in some situations. Specifically, functions defined like Class.prototype.func = function() { and functions defined like Class.func = function() { may automatically detect their container without any need to tag specially.
  • defineProperties on the other hand, must still use @memberof. JSDoc does not automatically connect properties with their class.
• Standardize callback/function parameter documentation #1085. I tested the @callback tag and it worked as expected.

Remaining JSDoc-specific problems:

• After Issue1434 #1729, array types do not create links to the element type. Not investigated yet.
• Modules containing functions do not show the function signature. Example binarySearch. This is because it can't tell whether the module is a function, or an object (example WindingOrder) This may be fixable in our template.
• Functions still must be declared as var Foo = function() instead of function Foo(). I assume this is a parsing problem in JSDoc that we cannot fix on our end.
• @link inside @default does not create a link in the documentation, e.g., @default {@link Cartesian3.ZERO} just turns into Cartesian3.ZERO. @link tags elsewhere appear to work.

[pjcozzi]

HTML in comments in code examples should not be escaped. See BaseLayerPicker for an example of the problem.

BaseLayerPicker is the only instance of this and was fixed in af99825. Context (@private) and GoogleEarthImageryProvider are also escaped but not in example comments so the generated doc is OK. Anything else needed here?

[pjcozzi]

I think I'm done here.

• Standardize callback/function parameter documentation #1085 with @callback - someone else will be faster than me for this one.
• Escaped HTML in comments is fixed AFAIK.
• The only DOC_TBA needing attention is in AnimationCollection, AnimationCollection usability improvements #1188.

@shunter want to close this and open a roadmap or something for the JSDoc-specific problems?

[pjcozzi]

Added this above to JSDoc-specific problems:

• @link inside @default does not create a link in the documentation, e.g., @default {@link Cartesian3.ZERO} just turns into Cartesian3.ZERO. @link tags elsewhere appear to work.

[pjcozzi]

@shunter should we close this and open a separate post-1.0 issue to track the JSDoc-specific problems?

[shunter]

Fine with me.