Document function behavior

The utility function formatCurrency is undocumented and new hires keep misusing it. Add a short function comment above formatCurrency in utils/format.js describing its inputs, return value, currency fallback, rounding behavior, and side effects; include one example of expected output for 1234.5 with USD. Commit as 'docs: document formatCurrency behavior' so reviewers can check examples.

Before I add the doc comment for formatCurrency, surface the important behavior so reviewers don't have to read the code: state the allowed input types, what happens with null or undefined, the default currency and locale, rounding rules, and whether it mutates its argument. Flag any edge cases like very large numbers or negative values that a reviewer should test.

A teammate passed null to formatCurrency and it returned 'NaN' in the UI. I wrote the function but I can't recall whether it should accept null or throw. I’m afraid documenting the wrong behavior will lock us into a bug. What is the most defensible behavior to document now, and how should I add one-line examples and a note for future maintainers about desired changes without breaking callers?

Over several projects we document utilities inconsistently, causing misuse and bug reports. Documentation either repeats the code or omits behavior like edge-case handling and examples. Which documentation habit will reduce developer confusion fastest: adopting a one-paragraph rule-set for each exported function, adding unit-test-backed examples, or enforcing a template via PR checklist? Which gives the best trade-off for our 3-person frontend team?