Function metadata: usage examples, documentation URL, parameter descriptions (HF-300)

[marcin-kordas-hoc]

What & why

HF-300 enriches the function-metadata API (getFunctionDetails) so every built-in function returns, in addition to the existing short description and parameter names:

• a usage example (≥1 per function),
• a documentation URL — a single shared URL for all functions in v1 (https://hyperformula.handsontable.com/docs/guide/built-in-functions.html), and
• a short description for each parameter.

Everything is English (translations are a later phase; the structure is already i18n-ready). Extends the SUM/SUMIF exemplar already on the base branch to the whole catalogue (363 functions).

Base: feature/hf-249-function-metadata-api (#1692). Sibling: #1699 (docs single source).

How

• The single documentation URL is defined once as DEFAULT_DOCUMENTATION_URL in buildFunctionDescriptions.ts and applied as the built-in default — not repeated per function. Custom (user-registered) functions keep ''.
• examples + per-parameter description authored per category file (categories/*.ts). Parameter counts/names and entry order are unchanged; only bodies were filled.

Testing (in the paired hyperformula-tests PR)

• Coverage-parity: every listable built-in exposes the shared URL, ≥1 example, and a non-empty description for every parameter.
• Example-validity: every authored example is built in HyperFormula and asserted not to be a parse (#ERROR!) or unknown-function (#NAME?) error.
• Existing SUM/SUMIF assertions updated to the .html URL.
• Arity guard (buildFunctionDetails) stays green across all 363 functions.

Local gates: tsc (src+test) clean · eslint clean · full jest 0 failures · metadata+coverage+example-validity specs pass.

Notes for review

• No i18n changes — by design. DoD scopes HF-300 to English; no functions are added/renamed, so the 17-language-pack rule does not apply. English-form examples show under every locale for now (accepted "translations later" trade-off).
• Operators (HF.ADD, …) are listable built-ins, so they get examples/descriptions per the DoD's "each function".
• Aliases inherit their target's authored doc automatically (resolveFunctionMetadata), so they need no separate authoring.
• Guide table untouched → the HF-249 bullet 3: generate built-in functions docs from the HF API (single source of truth) #1699 docs drift-check stays green (none of the new fields are rendered in the Function ID/Description/Syntax table).
• Descriptions describe HyperFormula's actual behavior (verified against the plugins), not Excel where they diverge — e.g. MOD result takes the sign of the dividend, FILTER accepts a single row/column, XNPV's first date is the reference point.

Decisions and citations: ADR in the paired hyperformula-tests repo (adr/2026-07-13-hf300-function-metadata-enrichment.md).

Source: https://app.clickup.com/t/86caprtgj

---

Note

Low Risk
Documentation and metadata-only changes for the function catalogue API; formula evaluation paths are unchanged aside from richer getFunctionDetails output.

Overview
HF-300 fills out built-in function catalogue metadata so getFunctionDetails() returns usage examples, per-parameter descriptions, and a documentation URL for every built-in (custom functions still get empty strings / empty arrays).

buildFunctionDescriptions now defines DEFAULT_DOCUMENTATION_URL and uses it when a catalogue entry omits documentationUrl, so callers always see the shared built-in-functions guide link instead of ''. Type and builder comments in FunctionDescription.ts are updated to match this “fully authored” catalogue phase.

The bulk of the change is hand-authored examples and non-empty parameters[].description across all categories/*.ts files (363 functions). The hf249-migrate-function-docs script is documented as destructive to those fields if re-run without merge preservation.

SUM/SUMIF no longer set a per-function documentationUrl locally—they rely on the shared default like other built-ins.

^{Reviewed by Cursor Bugbot for commit 7dbd891. Bugbot is set up for automated code reviews on this repo. Configure here.}

[qunabu]

Task linked: HF-300 Params descriptions, links and examples

[github-actions]

Performance comparison of head (7dbd891) vs base (2d9196e)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 489.33 | 494.04 | +0.96%
                                      Sheet B | 155.16 |  159.4 | +2.73%
                                      Sheet T | 139.78 | 142.87 | +2.21%
                                Column ranges | 468.35 | 466.55 | -0.38%
Sheet A:  change value, add/remove row/column |  15.27 |   15.1 | -1.11%
 Sheet B: change value, add/remove row/column | 134.52 | 132.15 | -1.76%
                   Column ranges - add column | 142.02 | 149.62 | +5.35%
                Column ranges - without batch | 434.55 | 459.05 | +5.64%
                        Column ranges - batch | 112.65 | 116.42 | +3.35%

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (feature/hf-249-function-metadata-api@2d9196e). Learn more about missing BASE report.

Additional details and impacted files

@@                           Coverage Diff                           @@
##             feature/hf-249-function-metadata-api    #1705   +/-   ##
=======================================================================
  Coverage                                        ?   96.86%           
=======================================================================
  Files                                           ?      192           
  Lines                                           ?    15590           
  Branches                                        ?     3447           
=======================================================================
  Hits                                            ?    15102           
  Misses                                          ?      488           
  Partials                                        ?        0           

Files with missing lines	Coverage Δ
...nterpreter/functionMetadata/FunctionDescription.ts	100.00% <ø> (ø)
...eter/functionMetadata/buildFunctionDescriptions.ts	100.00% <100.00%> (ø)
.../functionMetadata/categories/array-manipulation.ts	100.00% <ø> (ø)
...nterpreter/functionMetadata/categories/database.ts	100.00% <ø> (ø)
...reter/functionMetadata/categories/date-and-time.ts	100.00% <ø> (ø)
...rpreter/functionMetadata/categories/engineering.ts	100.00% <ø> (ø)
...terpreter/functionMetadata/categories/financial.ts	100.00% <ø> (ø)
...rpreter/functionMetadata/categories/information.ts	100.00% <ø> (ø)
...interpreter/functionMetadata/categories/logical.ts	100.00% <ø> (ø)
...unctionMetadata/categories/lookup-and-reference.ts	100.00% <ø> (ø)
... and 5 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sequba]

I don't like this default. It may become obsolete easily. Set 'https://hyperformula.handsontable.com/docs/guide/built-in-functions.html' for all functions in FunctionDoc files.

[sequba]

We don't need separate changelog for it

[sequba]

Resolve merge conflicts