docs: replace TODO docstring placeholders with accurate descriptions

[Alexx3890]

Related Issue / Discussion

Relates to codebase cleanup and documentation completeness by addressing lingering TODO: add description docstring stubs across core routing and constraint modules.

Changes

Please list the central functionalities that have been changed:

• Modified WeatherRoutingTool/algorithms/isobased.py

  • Replaced the TODO docstrings in IsoBased.terminate() and IsoBased.check_bearing() with accurate Sphinx-style documentation detailing route finalization and destination-overshoot handling.

• Modified WeatherRoutingTool/algorithms/isochrone.py

  • Replaced the TODO docstring on the IsoChrone class with documentation explaining the equal-time-step routing concept and clarifying its current unused status.

• Modified WeatherRoutingTool/algorithms/isofuel.py

  • Replaced the placeholder docstrings in IsoFuel.determine_timespread() and IsoFuel.final_pruning() with precise descriptions of statistical diagnostics and route candidate pruning.

• Modified WeatherRoutingTool/constraints/constraints.py

  • Replaced the placeholder docstrings in ConstraintsList.safe_crossing_continuous() and SeamarkCrossing.build_seamark_query() with detailed parameter and return type descriptions, as well as SQL query generation context.

• Modified WeatherRoutingTool/constraints/route_postprocessing.py

  • Replaced the placeholder docstring in RoutePostprocessing.post_process_route() with an explanation of Traffic Separation Scheme intersection handling and rerouting.

Further Details

Summary

Across several core modules in WeatherRoutingTool, several functions and classes had generic stub docstrings of the form:

"""TODO: add description
_summary_
"""

This PR replaces 8 placeholder docstrings across 5 files with complete, accurate Sphinx-compatible documentation derived directly from the underlying implementations.

The documentation includes correct parameter and return type information. In particular, build_seamark_query() is correctly documented with a return type of list[str], rather than a single string.

No functional code or runtime logic has been modified. This is strictly a documentation improvement that enhances IDE autocompletion, developer experience, and documentation generation.

Dependencies

None (no new dependencies required).

Testing

The existing test suite was executed successfully with 169 tests passing and no new error messages.

Since this PR only modifies documentation and does not introduce or modify runtime functionality, no new unit tests were added.

PR Checklist

In the context of this PR, I:

• have (already previously) filled the [52North Contributor License Agreement](https://52north.org/software/licensing/cla-guidelines/) and received positive feedback on this matter
• have filled the [52North Contributor License Agreement](https://52north.org/software/licensing/cla-guidelines/) and am waiting for feedback
• provide unit tests embedded in the WRT test framework (WeatherRoutingTool/tests) that allow the simple testing of the new/modified functionalities. All (previous and new) unit tests execute without new error messages. (N/A — documentation-only change; existing test suite passes with 169 tests and no new errors)
• ensure that the [code formatter](https://github.com/52North/WeatherRoutingTool/blob/main/flake8.sh) runs without errors/warnings
• ensure that my changes follow the [WRT's guidelines for contributing](https://52north.github.io/WeatherRoutingTool/source/contributing.html) at the time of the contribution

[Copilot]

🟡 Changes recommended

Several docstrings inaccurately describe control flow, inputs, and route-result behavior.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This documentation-only PR replaces eight TODO docstring placeholders with Sphinx-compatible descriptions; runtime logic is unchanged.

Changes:

• Documents routing termination, bearing checks, IsoChrone behavior, and IsoFuel pruning.
• Clarifies constraint checks and seamark query construction.
• Documents Traffic Separation Scheme route post-processing.

File summaries

File	Reviewed change
WeatherRoutingTool/constraints/route_postprocessing.py	Documents TSS route post-processing
WeatherRoutingTool/constraints/constraints.py	Documents constraint checks and seamark queries
WeatherRoutingTool/algorithms/isofuel.py	Documents diagnostics and candidate pruning
WeatherRoutingTool/algorithms/isochrone.py	Documents the IsoChrone algorithm
WeatherRoutingTool/algorithms/isobased.py	Documents route finalization and destination handling

Review details

Suppressed comments (4)

WeatherRoutingTool/algorithms/isobased.py:1575

• The method can return self.route_list[0] before extracting or reversing any arrays when multiple routes are requested. The unconditional wording here says those operations always occur, so document the prebuilt-route branch separately.

        Handles error and incomplete states (destination not reached, pruning
        errors), then extracts per-step arrays (lats, lons, fuel, speed, time,
        ship parameters, etc.) from the accumulated routing data.  The arrays
        are reversed because the search builds them back-to-front, and the
        result is wrapped in a :class:`RouteParams` object ready to be

WeatherRoutingTool/algorithms/isobased.py:1651

• This description is only accurate for the final destination. The method compares against finish_temp, which can be an intermediate waypoint; when any course reaches a waypoint, it sets all candidate endpoints to that waypoint rather than clipping only an overshooting candidate. Document the temporary-destination and waypoint behavior.

        Check whether any candidate course would overshoot the destination.

        Compares the remaining distance-to-destination for each candidate
        against the step distance.  If a candidate would pass the
        destination, it is clipped to point directly at the finish via

WeatherRoutingTool/constraints/constraints.py:1031

• This describes a narrower query than the implementation builds. The SQL selects both nodes and ways, and its predicate is (category_clause OR seamark:type=restricted_area), so a feature with the restricted-area tag is included even without one of the listed categories; it is not limited to restricted-area polygons matching a category.

        Constructs a tag-based query against the OpenStreetMap database to
        retrieve polygons tagged with ``seamark:type=restricted_area`` and
        matching category values (e.g. military, nature_reserve, minefield).

WeatherRoutingTool/constraints/constraints.py:1040

• set_map_bbox reads .lat1, .lat2, .lon1, and .lon2, and callers pass a Map instance, not a tuple. Documenting tuple gives consumers the wrong input contract.

        :type map_size: tuple or None, optional

• Files reviewed: 5/5 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.