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
Metadata and public API shape changes only; no formula evaluation or runtime logic paths are modified.

Overview
HF-300 fills the function-metadata catalogue so getFunctionDetails can expose full English help for every built-in, not just names and short blurbs.

Each entry in categories/*.ts now includes a shared documentationUrl (built-in-functions.html), at least one examples formula, and non-empty per-parameter description text (HyperFormula-specific behavior where it differs from Excel). Type comments in FunctionDescription.ts and buildFunctionDescriptions.ts are updated to match: built-ins are expected to ship authored docs; documentationUrl is passed through from the catalogue instead of defaulting to ''.

The HF-249 migration script is documented with a warning that regenerating category files from the guide wipes hand-authored examples and parameter descriptions. Category file headers note the same. INT’s short description is tightened to match truncate-toward-zero semantics.

^{Reviewed by Cursor Bugbot for commit 90fdd26. 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 (90fdd26) vs base (40b6468)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 389.83 | 389.14 | -0.18%
                                      Sheet B | 127.31 | 127.33 | +0.02%
                                      Sheet T | 109.02 | 110.52 | +1.38%
                                Column ranges | 411.59 | 410.53 | -0.26%
Sheet A:  change value, add/remove row/column |  12.88 |  13.13 | +1.94%
 Sheet B: change value, add/remove row/column | 112.58 | 113.94 | +1.21%
                   Column ranges - add column | 127.57 | 125.23 | -1.83%
                Column ranges - without batch |  394.1 | 386.42 | -1.95%
                        Column ranges - batch | 104.38 | 100.87 | -3.36%

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

[marcin-kordas-hoc]

Done in e634594. Removed the ?? DEFAULT_DOCUMENTATION_URL builder fallback — documentationUrl is now a required FunctionDoc field, set explicitly on every catalogue entry via the shared DEFAULT_DOCUMENTATION_URL const (moved to FunctionDescription.ts). buildFunctionDetails reads doc.documentationUrl directly.

[sequba]

@cursor remove this shared const entirely. Every function should set it as a regular string literal

[cursor]

Perfect! I've successfully removed the DEFAULT_DOCUMENTATION_URL constant entirely. Here's what I did:

Changes made:

• Removed the constant definition from FunctionDescription.ts
• Removed the re-export from buildFunctionDescriptions.ts
• Updated all 13 category files to use the literal string 'https://hyperformula.handsontable.com/docs/guide/built-in-functions.html' directly (366 total occurrences replaced)
• Updated JSDoc comments that referenced the removed constant

Commits:

• d5229a30d - Remove DEFAULT_DOCUMENTATION_URL constant, use literal strings
• 9c52d849b - Remove stale references to DEFAULT_DOCUMENTATION_URL in JSDoc comments

All changes have been pushed to feature/hf-300-metadata-enrichment.

  

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.87%. Comparing base (40b6468) to head (e634594).

Additional details and impacted files

@@                           Coverage Diff                            @@
##           feature/hf-249-function-metadata-api    #1705      +/-   ##
========================================================================
+ Coverage                                 96.43%   96.87%   +0.43%     
========================================================================
  Files                                       192      192              
  Lines                                     15589    15603      +14     
  Branches                                   3447     3446       -1     
========================================================================
+ Hits                                      15034    15115      +81     
+ Misses                                      555      488      -67     

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

... and 7 files 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.

[qunabu]

Task linked: HF-249 HF function documentation available via API