Problem with Shape `intersection` return type.

[pixelzoom]

Encountered while working on https://github.com/phetsims/geometric-optics/issues/229.

Geometric Optics makes calls to Shape intersection, which is defined as:

  /**
   * Hit-tests this shape with the ray. An array of all intersections of the ray with this shape will be returned.
   * For details, see the documentation in Segment.js
   * @public
   *
   * @param {Ray2} ray
   * @returns {Array.<Intersection>} - See Segment.js for details. For this function, intersections will be returned
   *                                   sorted by the distance from the ray's position.
   */
  intersection( ray ) {

The Array.<Intersection> type is problematic for TypeScript. As far as I can tell, there is no such type, it's a non-existent abstraction used in documentation.

Segment.js says:

   *   intersection( ray )      - returns a list of intersections between the segment and the ray. Intersections will be
   *                              of the {RayIntersection} type (see documentation there for details)
   *

So can we simply change the return type of Shape intersection to @returns {Array.<RayIntersection>}? Or some union of the concrete Intersection types?

[pixelzoom]

By the way... Navigating to Intersection from Shape's @returns {Array.<Intersection>} takes me to an unreleated class with the same name in bending-light.

[pixelzoom]

After inspecting what intersection is returning in geomtric-optics, I change my method param to {Array.<RayIntersection>}, see above commit. TS is happy now and requires no @ts-ignore.

[jonathanolson]

Apologies about the improper type docs! This looks like it's working well, anything else to do?

[pixelzoom]

👍🏻 closing