Improve documentation of math_util

2 files changed, 31 insertions, 15 deletions

diff --git a/include/math_util.h b/include/math_util.h
index 1ccde1ef5..b1243df56 100644
--- a/include/math_util.h
+++ b/include/math_util.h
@@ -1,11 +1,26 @@
 #ifndef GUARD_MATH_UTIL_H
 #define GUARD_MATH_UTIL_H
 
-s16 invfx16(s16 y);
-s16 mulfx16(s16 x, s16 y);
-s32 divfx32(s32 x, s32 y);
-s32 mulfx32(s32 x, s32 y);
-s16 divfxn16(u8 s, s16 x, s16 y);
-s16 mulfxn16(u8 s, s16 x, s16 y);
+// Fixed-point arithmetic library.
+
+// Proposed TODO: Move the macros here from global.h
+typedef s16 fx16;  // Fixed-point Q8.8
+typedef s16 fxn16; // Fixed-point with arbitrary precision (QN.S)
+typedef s32 fx32;  // Fixed-point Q24.8
+
+// x * y
+fx16 mulfx16(fx16 x, fx16 y);
+fxn16 mulfxn16(u8 s, fxn16 x, fxn16 y);
+fx32 mulfx32(fx32 x, fx32 y);
+
+// x / y
+fx16 divfx16(fx16 x, fx16 y);
+fxn16 divfxn16(u8 s, fxn16 x, fxn16 y);
+fx32 divfx32(fx32 x, fx32 y);
+
+// 1.0 / y
+fx16 invfx16(fx16 y);
+fxn16 invfxn16(u8 s, fxn16 y);
+fx32 invfx32(fx32 y);
 
 #endif //GUARD_MATH_UTIL_H
diff --git a/src/math_util.c b/src/math_util.c
index d4e2f3f56..e13c36ea6 100644
--- a/src/math_util.c
+++ b/src/math_util.c
@@ -1,6 +1,7 @@
 #include "global.h"
+#include "math_util.h"
 
-s16 mulfx16(s16 x, s16 y)
+fx16 mulfx16(fx16 x, fx16 y)
 {
     s32 result;
 
@@ -10,7 +11,7 @@ s16 mulfx16(s16 x, s16 y)
     return result;
 }
 
-s16 mulfxn16(u8 s, s16 x, s16 y)
+fxn16 mulfxn16(u8 s, fxn16 x, fxn16 y)
 {
     s32 result;
 
@@ -20,7 +21,7 @@ s16 mulfxn16(u8 s, s16 x, s16 y)
     return result;
 }
 
-s32 mulfx32(s32 x, s32 y)
+fx32 mulfx32(fx32 x, fx32 y)
 {
     s64 result;
 
@@ -30,7 +31,7 @@ s32 mulfx32(s32 x, s32 y)
     return result;
 }
 
-s16 divfx16(s16 x, s16 y)
+fx16 divfx16(fx16 x, fx16 y)
 {
     if (y == 0)
     {
@@ -39,7 +40,7 @@ s16 divfx16(s16 x, s16 y)
     return (x << 8) / y;
 }
 
-s16 divfxn16(u8 s, s16 x, s16 y)
+fxn16 divfxn16(u8 s, fxn16 x, fxn16 y)
 {
     if (y == 0)
     {
@@ -48,7 +49,7 @@ s16 divfxn16(u8 s, s16 x, s16 y)
     return (x << s) / y;
 }
 
-s32 divfx32(s32 x, s32 y)
+fx32 divfx32(fx32 x, fx32 y)
 {
     s64 _x;
 
@@ -61,7 +62,7 @@ s32 divfx32(s32 x, s32 y)
     return _x / y;
 }
 
-s16 invfx16(s16 y)
+fx16 invfx16(fx16 y)
 {
     s32 x;
 
@@ -69,7 +70,7 @@ s16 invfx16(s16 y)
     return x / y;
 }
 
-s16 invfxn16(u8 s, s16 y)
+fxn16 invfxn16(u8 s, fxn16 y)
 {
     s32 x;
 
@@ -77,7 +78,7 @@ s16 invfxn16(u8 s, s16 y)
     return x / y;
 }
 
-s32 invfx32(s32 y)
+fx32 invfx32(fx32 y)
 {
     s64 x;