Math::Geometry: improve documentation of intersection functions.

src/Magnum/Math/Geometry/Intersection.h

@@ -44,14 +44,17 @@ namespace Magnum { namespace Math { namespace Geometry { namespace Intersection
 @param q        Starting point of second line segment
 @param s        Direction of second line segment
 
-Returns intersection point positions @f$ t @f$, @f$ u @f$ on both lines, NaN if
+Returns intersection point positions @f$ t @f$, @f$ u @f$ on both lines:
-the lines are collinear or infinity if they are parallel. Intersection point
+
-can be then calculated with @f$ \boldsymbol{p} + t \boldsymbol{r} @f$ or
+-   @f$ t, u = \mathrm{NaN} @f$ if the lines are collinear
-@f$ \boldsymbol{q} + u \boldsymbol{s} @f$. If @f$ t @f$ is in range
+-   @f$ t \in [ 0 ; 1 ] @f$ if the intersection is inside the line segment
-@f$ [ 0 ; 1 ] @f$, the intersection is inside the line segment defined by
+    defined by @f$ \boldsymbol{p} @f$ and @f$ \boldsymbol{p} + \boldsymbol{r} @f$
-@f$ \boldsymbol{p} @f$ and @f$ \boldsymbol{p} + \boldsymbol{r} @f$, if @f$ u @f$
+-   @f$ t \notin [ 0 ; 1 ] @f$ if the intersection is outside the line segment
-is in range @f$ [ 0 ; 1 ] @f$, the intersection is inside the line segment
+-   @f$ u \in [ 0 ; 1 ] @f$ if the intersection is inside the line segment
-defined by @f$ \boldsymbol{q} @f$ and @f$ \boldsymbol{q} + \boldsymbol{s} @f$.
+    defined by @f$ \boldsymbol{q} @f$ and @f$ \boldsymbol{q} + \boldsymbol{s} @f$
+-   @f$ u \notin [ 0 ; 1 ] @f$ if the intersection is outside the line segment
+-   @f$ t, u \in \{-\infty, \infty\} @f$ if the intersection doesn't exist (the
+    2D lines are parallel)
 
 The two lines intersect if @f$ t @f$ and @f$ u @f$ exist such that: @f[
      \boldsymbol p + t \boldsymbol r = \boldsymbol q + u \boldsymbol s
@@ -70,7 +73,9 @@ for @f$ t @f$ and similarly for @f$ u @f$: @f[
 See also @ref lineSegmentLine() which calculates only @f$ t @f$, useful if you
 don't need to test that the intersection lies inside line segment defined by
 @f$ \boldsymbol{q} @f$ and @f$ \boldsymbol{q} + \boldsymbol{s} @f$.
-    */
+
+@see @ref isInf(), @ref isNan()
+*/
 template<class T> inline std::pair<T, T> lineSegmentLineSegment(const Vector2<T>& p, const Vector2<T>& r, const Vector2<T>& q, const Vector2<T>& s) {
     const Vector2<T> qp = q - p;
     const T rs = cross(r, s);
@@ -84,13 +89,18 @@ template<class T> inline std::pair<T, T> lineSegmentLineSegment(const Vector2<T>
 @param q        Starting point of second line
 @param s        Direction of second line
 
-Returns intersection point position @f$ t @f$ on first line, NaN if the lines
+Returns intersection point position @f$ t @f$ on the first line:
-are collinear or infinity if they are parallel. Intersection point can be then
+
-calculated with @f$ \boldsymbol{p} + t \boldsymbol{r} @f$. If returned value is
+-   @f$ t = \mathrm{NaN} @f$ if the lines are collinear
-in range @f$ [ 0 ; 1 ] @f$, the intersection is inside the line segment defined
+-   @f$ t \in [ 0 ; 1 ] @f$ if the intersection is inside the line segment
-by @f$ \boldsymbol{p} @f$ and @f$ \boldsymbol{p} + \boldsymbol{r} @f$.
+    defined by @f$ \boldsymbol{p} @f$ and @f$ \boldsymbol{p} + \boldsymbol{r} @f$
+-   @f$ t \notin [ 0 ; 1 ] @f$ if the intersection is outside the line segment
+-   @f$ t \in \{-\infty, \infty\} @f$ if the intersection doesn't exist (the 2D
+    lines are parallel)
 
 Unlike @ref lineSegmentLineSegment() calculates only @f$ t @f$.
+
+@see @ref isInf(), @ref isNan()
 */
 template<class T> inline T lineSegmentLine(const Vector2<T>& p, const Vector2<T>& r, const Vector2<T>& q, const Vector2<T>& s) {
     return cross(q - p, s)/cross(r, s);
@@ -103,11 +113,13 @@ template<class T> inline T lineSegmentLine(const Vector2<T>& p, const Vector2<T>
 @param p                Starting point of the line
 @param r                Direction of the line
 
-Returns intersection point position @f$ t @f$ on the line, NaN if the line lies
+Returns intersection point position @f$ t @f$ on the line:
-on the plane or infinity if the intersection doesn't exist. Intersection point
+
-can be then calculated from with @f$ \boldsymbol{p} + t \boldsymbol{r} @f$. If
+-   @f$ t = \mathrm{NaN} @f$ if the line lies on the plane
-returned value is in range @f$ [ 0 ; 1 ] @f$, the intersection is inside the
+-   @f$ t \in [ 0 ; 1 ] @f$ if the intersection is inside the line segment
-line segment defined by @f$ \boldsymbol{p} @f$ and @f$ \boldsymbol{r} @f$.
+    defined by @f$ \boldsymbol{p} @f$ and @f$ \boldsymbol{p} + \boldsymbol{r} @f$
+-   @f$ t \notin [ 0 ; 1 ] @f$ if the intersection is outside the line segment
+-   @f$ t \in \{-\infty, \infty\} @f$ if the intersection doesn't exist
 
 First the parameter @f$ f @f$ of parametric equation of the plane is calculated
 from plane normal @f$ \boldsymbol{n} @f$ and plane position: @f[
@@ -122,7 +134,9 @@ calculated and returned. @f[
          \Rightarrow t & = & \cfrac{f - \boldsymbol n \cdot \boldsymbol p}{\boldsymbol n \cdot \boldsymbol r}
      \end{array}
 @f]
-    */
+
+@see @ref isInf(), @ref isNan()
+*/
 template<class T> inline T planeLine(const Vector3<T>& planePosition, const Vector3<T>& planeNormal, const Vector3<T>& p, const Vector3<T>& r) {
     const T f = dot(planePosition, planeNormal);
     return (f - dot(planeNormal, p))/dot(planeNormal, r);