Full type annotations + Doxygen docs; pyright clean

[mmmarinho]

Summary

Follow-up to #9: makes the merged code fully annotated and checkable with pyright and adds Doxygen-style documentation everywhere it was missing.

• pyright: 0 errors, 0 warnings (standard mode, 7 files analyzed — was 129 errors / 4 warnings before this work).
• No behavioral change: all logic preserved. Verified by a logic-diff against origin/main (differences are annotations/docstrings/type-safety guards only), a full rebuild of the _core extension from the new C++ sources, and a runtime smoke test of the controller API.

Changes

Python (full annotations + Doxygen docstrings)

• marinholab/working/needlemanipulation/_impl.py, icra2019_controller.py, needle_controller.py: complete parameter/return annotations, Args:/Returns:/Raises: docstrings, module docstrings.
• Fixed real type bugs along the way:
  • np.array used as a type → np.ndarray
  • bare tuple return annotations (-> (A, B)) → Tuple[A, B]
  • last_x / last_Jx / last_error initialized to None without Optional
  • constraint_counter possibly-unbound (hoisted the = 0 out of the verbose branch)
  • ns_vessel typed list[DQ] but accepts None → list[DQ] | None
  • get_last_robot_pose() returns DQ | None from a DQ return type
• example*.py and saul/insertion_1.py: module/function docstrings + annotations (examples are excluded from the pyright check via exclude in pyproject.toml).
• marinholab/working/needlemanipulation/_core.pyi: fixed the self-referential ActuationType type alias.

C++ (Doxygen @file / @brief / @param / @return / @throws)

• include/M3_SerialManipulatorSimulatorFriendly.h
• src/M3_SerialManipulatorSimulatorFriendly.cpp (protected helpers _get_w, _joint_transformation + file header)

Type infrastructure

• stubs/dqrobotics/: closed-set .pyi stubs (__init__, robot_modeling, utils, solvers) for the untyped compiled dqrobotics package, declaring only the symbols this project imports. This is what lets the rest of the codebase be checked without globally weakening the checks. Wired up via stubPath = "stubs" in pyproject.toml.
• stubs/ is intentionally not packaged: [tool.setuptools.packages.find] include = ["marinholab*"] keeps it out of the wheel.

Documentation

• AGENTS.md: new sections for the pyright/stubs workflow and the annotation + Doxygen conventions; fixed stale references to the tests/ suite and the CI test job (both removed in Bring needle constraint work from simulator_tests (keep main's CI and core) #9).

Verification

• pyright 1.1.411 (standard mode): 0 errors, 0 warnings, 0 informations (7 files analyzed).
• ast.parse on every touched Python file: OK.
• Logic diff vs origin/main (docstrings/comments/annotations stripped): identical for saul/insertion_1.py and _impl.py; for the two controllers, the only deltas are annotations and 3 defensive guards that cannot fire in normal operation (a last_x/last_Jx is None check right after it is set, a redundant w is not None alongside W is not None, and a bool() coercion of kwargs["verbose"]).
• Rebuilt _core from the new sources and reinstalled: build OK.
• Runtime smoke test (fresh install): all 6 package modules import; NeedleController._get_optimization_parameters returns finite H (9,9), f (9,), W (19–20, 9); get_last_robot_pose() → DQ; all 11 _impl constraint functions present and callable, including with ns_vessel=None.

This PR was created by an AI agent (OpenHands) on behalf of the user.

[mmmarinho]

👍