docs/fix: follow-ups to #341 Copilot review (remesh swallow contract, evaluate Returns)

[lmoresi]

Doc-only follow-ups to the two GitHub Copilot review comments on #341, which merged before these could land on the PR branch.

1. remesh.py _write_var_data swallow contract (Copilot comment 3533848061): the broad except Exception is pre-existing behaviour — the helper unified three identical broad try/except sites verbatim, and the snapshot twin had the same breadth before the wave. Behaviour is unchanged (readability-wave contract); the comment now states honestly that the breadth also swallows genuine write failures (shape/broadcast mismatches), not only the intended unallocated/size-0 skip, and carries a TODO(DESIGN) to narrow once the exception types raised by the unallocated-storage .data paths are established.

2. evaluate() Returns section (Copilot comment 3533848118): the WE-04 docstring said scaling-active evaluation returns a plain ndarray. The implementation follows the gateway principle — unit-aware results (UWQuantity / UnitAwareArray) whenever the expression carries units, regardless of scaling state; plain ndarray only for unitless expressions. Docstring fixed to match unwrap_for_evaluate / _evaluate_impl reality.

No behavioural change. File-local tests pass: test_0830_mesh_adapt_variable_transfer, test_0503_evaluate, test_0753_evaluate_nondimensional_scaling (22 passed).

Underworld development team with AI support from Claude Code

[Copilot]

Pull request overview

Doc-only follow-ups aligning documentation/comments with established behavior in remesh and unit-aware evaluation: clarifies that _write_var_data()’s broad exception swallow is pre-existing and explicitly documents its wider impact, and corrects uw.function.evaluate()’s return-type documentation to match the unit “gateway principle” implemented in _evaluate_impl.

Changes:

• Update evaluate() docstring “Returns” section to state that unit-aware outputs are returned whenever the expression carries units, regardless of whether non-dimensional scaling is active.
• Expand _write_var_data() swallow comment to document the intentional skip case vs. the broader exceptions being swallowed, and add a TODO(DESIGN) to narrow/report once exception types are known.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/underworld3/function/functions_unit_system.py	Fix evaluate() return-type documentation to reflect unit-aware wrapping/redimensionalisation behavior in _evaluate_impl.
src/underworld3/discretisation/remesh.py	Clarify the existing broad except Exception swallow contract in _write_var_data() and document its implications/TODO.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.