From 9df36ce005ee02e4bc9c01dd760d6f5aeb36ade3 Mon Sep 17 00:00:00 2001
From: Recep Aslantas <info@recp.me>
Date: Fri, 29 Mar 2024 08:05:10 +0300
Subject: [PATCH] docs: ray sphere docs improvements

---
 docs/source/ray.rst       | 2 ++
 include/cglm/ray.h        | 5 ++++-
 include/cglm/struct/ray.h | 4 ++++
 3 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/docs/source/ray.rst b/docs/source/ray.rst
index ab89b7a..d1f0a1d 100644
--- a/docs/source/ray.rst
+++ b/docs/source/ray.rst
@@ -36,6 +36,8 @@ Functions documentation
 
     ray sphere intersection
 
+    returns false if there is no intersection if true:
+
     - t1 > 0, t2 > 0: ray intersects the sphere at t1 and t2 both ahead of the origin
     - t1 < 0, t2 > 0: ray starts inside the sphere, exits at t2
     - t1 < 0, t2 < 0: no intersection ahead of the ray
diff --git a/include/cglm/ray.h b/include/cglm/ray.h
index 38e171a..841947e 100644
--- a/include/cglm/ray.h
+++ b/include/cglm/ray.h
@@ -82,6 +82,8 @@ glm_ray_triangle(vec3   origin,
 /*!
  * @brief ray sphere intersection
  *
+ * returns false if there is no intersection if true:
+ *
  * - t1 > 0, t2 > 0: ray intersects the sphere at t1 and t2 both ahead of the origin
  * - t1 < 0, t2 > 0: ray starts inside the sphere, exits at t2
  * - t1 < 0, t2 < 0: no intersection ahead of the ray
@@ -94,6 +96,8 @@ glm_ray_triangle(vec3   origin,
  * @param[in]  s      sphere  [center.x, center.y, center.z, radii]
  * @param[in]  t1     near point1 (closer to origin)
  * @param[in]  t2     far point2 (farther from origin)
+ *
+ * @returns whether there is intersection
  */
 CGLM_INLINE
 bool 
@@ -105,7 +109,6 @@ glm_ray_sphere(vec3 origin,
   vec3  dp;
   float r2, ddp, dpp, dscr, q, tmp, _t1, _t2;
 
-  /* ensure dir is normalized */
   glm_vec3_sub(s, origin, dp);
 
   ddp = glm_vec3_dot(dir, dp);
diff --git a/include/cglm/struct/ray.h b/include/cglm/struct/ray.h
index bd08801..d11be92 100644
--- a/include/cglm/struct/ray.h
+++ b/include/cglm/struct/ray.h
@@ -40,6 +40,8 @@ glms_ray_(triangle)(vec3s  origin,
 /*!
  * @brief ray sphere intersection
  *
+ * returns false if there is no intersection if true:
+ *
  * - t1 > 0, t2 > 0: ray intersects the sphere at t1 and t2 both ahead of the origin
  * - t1 < 0, t2 > 0: ray starts inside the sphere, exits at t2
  * - t1 < 0, t2 < 0: no intersection ahead of the ray
@@ -52,6 +54,8 @@ glms_ray_(triangle)(vec3s  origin,
  * @param[in]  s      sphere  [center.x, center.y, center.z, radii]
  * @param[in]  t1     near point1 (closer to origin)
  * @param[in]  t2     far point2 (farther from origin)
+ *
+ * @returns whether there is intersection
  */
 CGLM_INLINE
 bool