From 91461d0f87e376754f03a9b6bed8466d89381a42 Mon Sep 17 00:00:00 2001
From: John McCardle <mccardle.john@gmail.com>
Date: Thu, 30 Oct 2025 11:20:48 -0400
Subject: [PATCH] feat: convert PyVector to use documentation macros

Converts magnitude, normalize, and dot methods to MCRF_METHOD macro.
Docstrings now include complete Args/Returns/Raises sections.
Addresses issue #92.
---
 src/PyVector.cpp          | 25 ++++++++++++++++++++++---
 tools/test_vector_docs.py | 19 +++++++++++++++++++
 2 files changed, 41 insertions(+), 3 deletions(-)
 create mode 100644 tools/test_vector_docs.py

diff --git a/src/PyVector.cpp b/src/PyVector.cpp
index 16acd51..51cfbcf 100644
--- a/src/PyVector.cpp
+++ b/src/PyVector.cpp
@@ -1,5 +1,6 @@
 #include "PyVector.h"
 #include "PyObjectUtils.h"
+#include "McRFPy_Doc.h"
 #include <cmath>
 
 PyGetSetDef PyVector::getsetters[] = {
@@ -9,10 +10,28 @@ PyGetSetDef PyVector::getsetters[] = {
 };
 
 PyMethodDef PyVector::methods[] = {
-    {"magnitude", (PyCFunction)PyVector::magnitude, METH_NOARGS, "Return the length of the vector"},
+    {"magnitude", (PyCFunction)PyVector::magnitude, METH_NOARGS,
+     MCRF_METHOD(Vector, magnitude,
+         MCRF_SIG("()", "float"),
+         MCRF_DESC("Calculate the length/magnitude of this vector."),
+         MCRF_RETURNS("float: The magnitude of the vector")
+     )},
     {"magnitude_squared", (PyCFunction)PyVector::magnitude_squared, METH_NOARGS, "Return the squared length of the vector"},
-    {"normalize", (PyCFunction)PyVector::normalize, METH_NOARGS, "Return a unit vector in the same direction"},
-    {"dot", (PyCFunction)PyVector::dot, METH_O, "Return the dot product with another vector"},
+    {"normalize", (PyCFunction)PyVector::normalize, METH_NOARGS,
+     MCRF_METHOD(Vector, normalize,
+         MCRF_SIG("()", "Vector"),
+         MCRF_DESC("Return a unit vector in the same direction."),
+         MCRF_RETURNS("Vector: New normalized vector with magnitude 1.0")
+         MCRF_RAISES("ValueError", "If vector has zero magnitude")
+     )},
+    {"dot", (PyCFunction)PyVector::dot, METH_O,
+     MCRF_METHOD(Vector, dot,
+         MCRF_SIG("(other: Vector)", "float"),
+         MCRF_DESC("Calculate the dot product with another vector."),
+         MCRF_ARGS_START
+         MCRF_ARG("other", "The other vector")
+         MCRF_RETURNS("float: Dot product of the two vectors")
+     )},
     {"distance_to", (PyCFunction)PyVector::distance_to, METH_O, "Return the distance to another vector"},
     {"angle", (PyCFunction)PyVector::angle, METH_NOARGS, "Return the angle in radians from the positive X axis"},
     {"copy", (PyCFunction)PyVector::copy, METH_NOARGS, "Return a copy of this vector"},
diff --git a/tools/test_vector_docs.py b/tools/test_vector_docs.py
new file mode 100644
index 0000000..cb3f4ae
--- /dev/null
+++ b/tools/test_vector_docs.py
@@ -0,0 +1,19 @@
+import mcrfpy
+import sys
+
+# Check Vector.magnitude docstring
+mag_doc = mcrfpy.Vector.magnitude.__doc__
+print("magnitude doc:", mag_doc)
+assert "magnitude()" in mag_doc
+assert "Calculate the length/magnitude" in mag_doc
+assert "Returns:" in mag_doc
+
+# Check Vector.dot docstring
+dot_doc = mcrfpy.Vector.dot.__doc__
+print("dot doc:", dot_doc)
+assert "dot(other: Vector)" in dot_doc
+assert "Args:" in dot_doc
+assert "other:" in dot_doc
+
+print("SUCCESS: All docstrings present and complete")
+sys.exit(0)