docs: synchronize and standardize core and blender docstrings

Signed-off-by: arounamounchili <patouossa.mounchili@gmail.com>

Author: arounamounchili

core/src/linkforge_core/__init__.py

@@ -4,10 +4,10 @@
 It can be used standalone or integrated into various platforms (Blender, Unity, Web, etc.).
 
 Modules:
-    models: Data structures for robots, links, joints, geometry
+    models: Data structures for robots, links, joints, geometry, and SRDF
     physics: Inertia and mass calculations
-    parsers: URDF and XACRO file parsing
-    generators: URDF and XACRO file generation
+    parsers: URDF, XACRO, and SRDF file parsing
+    generators: URDF, XACRO, and SRDF file generation
 """
 
 from __future__ import annotations

core/src/linkforge_core/generators/__init__.py

@@ -1,4 +1,4 @@
-"""URDF and XACRO generators for converting robot models to file formats."""
+"""URDF, XACRO, and SRDF generators for converting robot models to file formats."""
 
 from .srdf_generator import SRDFGenerator
 from .urdf_generator import URDFGenerator

core/src/linkforge_core/models/__init__.py

@@ -1,9 +1,9 @@
 """Core data models for robot descriptions.
 
 This sub-package defines the foundational data structures that represent
-a robot's physical, kinematic, and sensor properties. These models are
-designed to be simulator-agnostic and form the central API for all
-LinkForge operations.
+a robot's physical, kinematic, sensor, and semantic (SRDF) properties.
+These models are designed to be simulator-agnostic and form the central API
+for all LinkForge operations.
 """
 
 from .gazebo import GazeboElement, GazeboPlugin

core/src/linkforge_core/models/graph.py

@@ -31,7 +31,7 @@ def __init__(self, links: Iterable[Link], joints: Iterable[Joint]) -> None:
             joints: Collection of Joint objects forming the edges of the graph.
 
         Raises:
-            RobotModelError: If a joint references a link not present in the links collection.
+            RobotValidationError: If a joint references a link not present in the links collection.
         """
         self.link_names = {link.name for link in links}
         self.joints = list(joints)
@@ -149,7 +149,7 @@ def get_topological_order(self) -> list[str]:
             List of link names
 
         Raises:
-            RobotModelError: If a cycle is detected
+            RobotValidationError: If a cycle is detected
         """
         if self.has_cycle():
             raise RobotValidationError("CyclicGraph", None, "Graph contains cycles")

core/src/linkforge_core/parsers/__init__.py

@@ -1,4 +1,4 @@
-"""URDF/XACRO parsers for importing robot models."""
+"""URDF, XACRO, and SRDF parsers for importing robot models."""
 
 from __future__ import annotations
 

core/src/linkforge_core/parsers/urdf_parser.py

@@ -785,7 +785,10 @@ def parse(self, filepath: Path, **_kwargs: Any) -> Robot:
             The generic Robot model (Intermediate Representation)
 
         Raises:
-            RobotParserError: If parsing fails
+            RobotParserIOError: If file cannot be read or exceeds size limit
+            XacroDetectedError: If a XACRO file is passed instead of URDF
+            RobotParserXMLRootError: If root tag is not <robot>
+            RobotParserUnexpectedError: If XML is malformed or internal error occurs
         """
         if not filepath.exists():
             raise RobotParserIOError(filepath=filepath, reason="File not found")
@@ -835,7 +838,22 @@ def parse_string(
         urdf_directory: Path | None = None,
         **_kwargs: Any,
     ) -> Robot:
-        """Parse URDF from string."""
+        """Parse URDF from string.
+
+        Args:
+            urdf_string: URDF XML content as string
+            urdf_directory: Base directory for relative mesh path resolution
+            **kwargs: Additional parsing options
+
+        Returns:
+            The generic Robot model (Intermediate Representation)
+
+        Raises:
+            RobotParserIOError: If string exceeds size limit
+            XacroDetectedError: If string contains XACRO markers
+            RobotParserXMLRootError: If root tag is not <robot>
+            RobotParserUnexpectedError: If XML parsing fails
+        """
         string_size = len(urdf_string.encode("utf-8"))
         if string_size > self.max_file_size:
             raise RobotParserIOError(filepath=Path("string"), reason="URDF string too large")

core/src/linkforge_core/parsers/xacro_parser.py

@@ -145,7 +145,8 @@ def resolve_file(self, filepath: Path) -> str:
             The fully resolved URDF XML as a string.
 
         Raises:
-            RobotParserError: If resolution fails or circular dependencies are found.
+            RobotXacroError: If resolution fails or internal error occurs
+            RobotXacroRecursionError: If circular dependencies are found
         """
         # Deeply nested XACRO files can exceed Python's default recursion limit (usually 1000)
         # We temporarily boost it to ensure we can handle complex industrial robots
@@ -206,6 +207,9 @@ def resolve_string(self, xml_string: str) -> str:
 
         Returns:
             The fully resolved XML as a string.
+
+        Raises:
+            RobotXacroError: If XML is malformed or resolution fails
         """
         old_limit = sys.getrecursionlimit()
         if old_limit < RECURSION_LIMIT_BOOST:
@@ -233,6 +237,10 @@ def _get_structural_template(self, filepath: Path) -> XacroTemplate:
 
         Returns:
             The cached or newly built structural template.
+
+        Raises:
+            RobotXacroRecursionError: If circular includes are detected
+            RobotXacroError: If XML parsing fails or files cannot be located
         """
         filepath = filepath.resolve()
         if filepath in TEMPLATE_CACHE:
@@ -336,7 +344,7 @@ def resolve_element(self, element: ET.Element) -> ET.Element:
             The resolved XML element or a container.
 
         Raises:
-            RobotParserError: If maximum recursion depth is exceeded.
+            RobotXacroRecursionError: If maximum recursion depth is exceeded
         """
         self._current_depth += 1
         if self._current_depth > self.max_depth:

core/src/linkforge_core/physics/inertia.py

@@ -425,7 +425,7 @@ def calculate_inertia(geometry: Geometry, mass: float) -> InertiaTensor:
         Inertia tensor about the center of mass
 
     Raises:
-        RobotModelError: If geometry type is not supported
+        RobotPhysicsError: If geometry type is not supported
 
     """
     if mass <= 0:

core/src/linkforge_core/utils/xml_utils.py

@@ -154,7 +154,21 @@ def parse_int(
     default: int | None = None,
     check_name: str | None = None,
 ) -> int:
-    """Parse integer value from XML with comprehensive validation."""
+    """Parse integer value from XML with comprehensive validation.
+
+    Args:
+        text: String to parse
+        attribute_name: Context for error messages
+        default: Default value if text is None
+        check_name: Alias for attribute_name for consistent reporting
+
+    Returns:
+        Parsed integer
+
+    Raises:
+        RobotMathError: If input format is invalid or value is out of range
+        RobotValidationError: If attribute is missing and no default is provided
+    """
     report_name = check_name or attribute_name
 
     if text is not None and not text.strip():
@@ -178,7 +192,18 @@ def parse_int(
 
 
 def parse_vector3(text: str) -> Vector3:
-    """Parse space-separated vector3 string."""
+    """Parse space-separated vector3 string.
+
+    Args:
+        text: Space-separated string (e.g. "1.0 2.0 3.0")
+
+    Returns:
+        Vector3 model
+
+    Raises:
+        RobotValidationError: If vector format is invalid or components are missing
+        RobotMathError: If component values are invalid
+    """
     parts = text.strip().split()
     if len(parts) != 3:
         raise RobotValidationError(check_name="Vector3", value=text, reason="Expected 3 values")
@@ -194,14 +219,36 @@ def parse_vector3(text: str) -> Vector3:
 
 
 def parse_optional_bool(elem: ET.Element, tag: str, default: str = "false") -> bool | None:
-    """Parse optional boolean element."""
+    """Parse optional boolean element.
+
+    Args:
+        elem: Parent XML element
+        tag: Sub-element tag to find
+        default: Default string value if tag is found but content is empty
+
+    Returns:
+        Boolean value if tag exists, else None
+    """
     if elem.find(tag) is not None:
         return elem.findtext(tag, default).lower() == "true"
     return None
 
 
 def parse_optional_float(elem: ET.Element, tag: str, default: float | None = 0.0) -> float | None:
-    """Parse optional float element."""
+    """Parse optional float element.
+
+    Args:
+        elem: Parent XML element
+        tag: Sub-element tag to find
+        default: Default float value if tag content is missing
+
+    Returns:
+        Parsed float if tag exists, else None
+
+    Raises:
+        RobotMathError: If input value is invalid or out of range
+        RobotValidationError: If parsing logic fails
+    """
     if elem.find(tag) is not None:
         text = elem.findtext(tag)
         return parse_float(text, tag, default=default)

core/src/linkforge_core/validation/__init__.py

@@ -2,7 +2,8 @@
 
 This sub-package provides the logic for ensuring robot models are structurally
 sound and safe for export. It includes checks for kinematic connectivity,
-physics validity, and security validation for external assets.
+physics validity, and semantic validation (e.g. SRDF collision matrices),
+as well as security validation for external assets.
 """
 
 from __future__ import annotations