docs/feat: improve shear stress logic with foundational physical principles

- Refactored interface to use None for unknown variables (more idiomatic)
- Enhanced documentation with core mechanical context
- Added robust error handling for physical constraints and division by zero

Author: definus6-dev

physics/shear_stress.py

@@ -1,59 +1,76 @@
 from __future__ import annotations
 
 """
-Shear stress is a component of stress that is coplanar to the material cross-section.
-It arises due to a shear force, the component of the force vector parallel to the
-material cross-section.
+In foundational mechanics, shear stress is defined as a stress component that acts
+parallel to the material's cross-section. It arises from a shear force, which is the
+component of the force vector acting coplanar with the cross-section.
 
-https://en.wikipedia.org/wiki/Shear_stress
+The relationship is governed by the core formula: tau = F / A
+where:
+    tau (τ) is the shear stress
+    F is the tangential force (shear force)
+    A is the cross-sectional area
+
+Reference: https://en.wikipedia.org/wiki/Shear_stress
 """
 
 
-def shear_stress(
-    stress: float,
-    tangential_force: float,
-    area: float,
-) -> tuple[str, float]:
+def calculate_shear_stress(
+    shear_stress: float | None = None,
+    tangential_force: float | None = None,
+    area: float | None = None,
+) -> float:
     """
-    This function can calculate any one of the three -
-    1. Shear Stress
-    2. Tangential Force
-    3. Cross-sectional Area
-    This is calculated from the other two provided values
-    Examples -
-    >>> shear_stress(stress=25, tangential_force=100, area=0)
-    ('area', 4.0)
-    >>> shear_stress(stress=0, tangential_force=1600, area=200)
-    ('stress', 8.0)
-    >>> shear_stress(stress=1000, tangential_force=0, area=1200)
-    ('tangential_force', 1200000)
+    Calculates the missing variable in the shear stress formula (tau = F / A).
+    Exactly two of the parameters must be provided.
+
+    Args:
+        shear_stress: The stress parallel to the cross-section (Pascal).
+        tangential_force: The force acting parallel to the cross-section (Newton).
+        area: The cross-sectional area (Square meters).
+
+    Returns:
+        The calculated missing value (shear_stress, tangential_force, or area).
+
+    Raises:
+        ValueError: If fewer or more than two parameters are provided,
+                    if a parameter is negative, or if a division by zero occurs.
+
+    Examples:
+        >>> calculate_shear_stress(tangential_force=100.0, area=4.0)
+        25.0
+        >>> calculate_shear_stress(shear_stress=8.0, area=200.0)
+        1600.0
+        >>> calculate_shear_stress(shear_stress=1000.0, tangential_force=1200000.0)
+        1200.0
     """
-    if (stress, tangential_force, area).count(0) != 1:
-        raise ValueError("You cannot supply more or less than 2 values")
-    elif stress < 0:
-        raise ValueError("Stress cannot be negative")
-    elif tangential_force < 0:
-        raise ValueError("Tangential Force cannot be negative")
-    elif area < 0:
-        raise ValueError("Area cannot be negative")
-    elif stress == 0:
-        return (
-            "stress",
-            tangential_force / area,
-        )
-    elif tangential_force == 0:
-        return (
-            "tangential_force",
-            stress * area,
-        )
-    else:
-        return (
-            "area",
-            tangential_force / stress,
-        )
+    params = (shear_stress, tangential_force, area)
+    none_count = params.count(None)
+
+    if none_count != 1:
+        raise ValueError("Exactly two values must be provided to calculate the third.")
+
+    # Validation: Physically, these values should not be negative in this context
+    if any(p is not None and p < 0 for p in params):
+        raise ValueError("Parameters cannot be negative.")
+
+    if shear_stress is None:
+        if area == 0:
+            raise ValueError("Area cannot be zero when calculating stress.")
+        return tangential_force / area
+
+    if tangential_force is None:
+        return shear_stress * area
+
+    if area is None:
+        if shear_stress == 0:
+            raise ValueError("Shear stress cannot be zero when calculating area.")
+        return tangential_force / shear_stress
+
+    return 0.0
 
 
 if __name__ == "__main__":
     import doctest
 
-    doctest.testmod()
+    doctest.testmod()