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: docs/adr/2026-07-13-hf300-function-metadata-enrichment.md.

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

🤖 Generated with Claude Code

[qunabu]

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

[github-actions]

Performance comparison of head (114d1e5) vs base (8207bf3)

                                     testName |   base |   head |  change
-------------------------------------------------------------------------
                                      Sheet A | 484.09 | 502.65 |  +3.83%
                                      Sheet B | 151.24 | 156.07 |  +3.19%
                                      Sheet T | 137.52 |  139.2 |  +1.22%
                                Column ranges | 466.92 | 475.37 |  +1.81%
Sheet A:  change value, add/remove row/column |  14.07 |  15.88 | +12.86%
 Sheet B: change value, add/remove row/column | 122.15 | 137.62 | +12.66%
                   Column ranges - add column |  138.9 | 152.18 |  +9.56%
                Column ranges - without batch | 426.68 | 455.26 |  +6.70%
                        Column ranges - batch | 111.73 | 118.24 |  +5.83%

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.19%. Comparing base (8207bf3) to head (114d1e5).

Additional details and impacted files

@@                           Coverage Diff                            @@
##           feature/hf-249-function-metadata-api    #1705      +/-   ##
========================================================================
+ Coverage                                 97.17%   97.19%   +0.02%     
========================================================================
  Files                                       192      192              
  Lines                                     15446    15447       +1     
  Branches                                   3412     3412              
========================================================================
+ Hits                                      15009    15014       +5     
+ Misses                                      437      433       -4     

Files with missing lines	Coverage Δ
...nterpreter/functionMetadata/FunctionDescription.ts	100.00% <ø> (ø)
...eter/functionMetadata/buildFunctionDescriptions.ts	96.00% <100.00%> (+0.16%)	⬆️
.../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

... and 1 file with indirect coverage changes

🚀 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.