(Open) SphereCast and all related pages are confusing


1) What happened
SphereCast and all related pages are confusing.
http://unity3d.com/support/documentation/ScriptReference/Physics.SphereCast.html

This is what's in the documentation:
-
Description
Casts a sphere against all colliders in the scene and returns detailed information on what was hit.
This is useful when a Raycast does not give enough precision, because you want to find out if an object of a specific size, such as a character, will be able to move somewhere without colliding with anything on the way. Think of the sphere cast like a thick raycast.
-

We had a long conversation about casting and the confusion in the documentation and there is one fundamental misunderstanding about how these volume casts work that is not addressed in the docs. This is also related to what the user's expectations are.

Most users come across SphereCast and don't understand it because they feel that SphereCasting should be "like a ray" but casting out in a sphere around the origin - Like OverlapSphere but instead of returning Collider[] is returns RaycastHit[].

This is not true, tho' people try to use it like this.

SphereCast moves a Sphere volume down the direction and distance of a ray and detects what it bumps into.

The following description "Casts a sphere against all colliders in the scene ..." in under descriptive and confusing.

This needs to be something like "Casts a sphere (radius) along a ray (origin, direction, distance) and returns an array containing detailed information on each collider which was hit by the sphere while traveling along the ray.

If you google/search "SphereCast" on the forums and answers, you will see that many (most?) people don't understand SphereCast and are using it improperly.