Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Migration

API docs vs. ts-defold-types

How the JSDoc that @defold-typescript/types emits compares with the incumbent hand-and-script-maintained thinknathan/ts-defold-types. Both surfaces derive from the same Defold reference docs, so symbol coverage is parity by construction; this page records where @defold-typescript/types' emitted documentation is strictly cleaner, and the one place ts-defold-types is arguably cleaner.

The comparison is backed by a machine check, packages/types/test/api-doc-parity.test.ts, which parses a pinned snapshot of the ts-defold-types index.d.ts and the @defold-typescript/types generated/*.d.ts with one shared extractor and fails if @defold-typescript/types documents less than ts-defold-types does for any shared symbol. It compares documentation, not type fidelity (branded vs. flat types are out of scope here).

Dimension comparison

Dimensionts-defold-types@defold-typescript/types
Description coverageMost functions/constants carry a summarySame source, same coverage; every shared symbol documents at least as well
Namespace hoverModule namespaces are not consistently documentedGenerated namespaces use Defold module metadata; (synthesized) marks fallback prose only when the ref-doc has no module summary
@param style@param <name> <desc> (no separator)@param <name> - <desc> (dash-separated, the JSDoc convention editors render as a definition list)
Description markupRaw ref-doc texthtmlToDocText converts HTML to Markdown: <code>→`code`, <ul><li>→- bullets, <a>→link text, entities decoded
Multi-line @param/@returnsContinuation lines escape the * gridEvery continuation line carries * (see the well-formedness gate)
@returnsOne flat @returns even for multi-value returnsOne @returns for single returns; multi-value returns are typed as a LuaMultiReturn tuple that names every value (see exceptions)
@example@example <prose> then a fenced block@example then a fenced ```lua block on its own lines
Constant typesconst X: numberBranded: number & { readonly __brand: "ns.X" } — distinct constants stay nominally distinct

Description markup, concretely

ts-defold-types:

 * @param options A table with the following fields: <ul><li><code>count</code> ...

@defold-typescript/types:

 * @param options - A table with the following fields:
 * - `count` ...

Well-formedness

A multi-line @param doc (a ref-doc <li> list becomes embedded newlines) is re-prefixed line by line so it stays inside the JSDoc * grid. The permanent guard for this is the self-contained packages/types/test/doc-comment-wellformed.test.ts gate over the committed generated/*.d.ts — it does not depend on the pinned fixture below.

Coverage-test result

Against the pinned snapshot (Defold stable 1.12.4):

  • 791 shared symbols — for every one, the @defold-typescript/types docs are a superset: if ts-defold-types has a description, a @param, a @returns, or an @example, @defold-typescript/types does too.
  • 106 ts-defold-types-only symbols — reported as coverage notes, not failures. These are surface-shape differences, not dropped docs: top-level globals (pprint, hash, …) and modules the @defold-typescript/types surface structures differently (b2d.body.*, bit.*, some socket overloads). They live elsewhere or under a different namespace path in the @defold-typescript/types split, branded/versioned surface.

Multi-return functions

For 9 functions whose Lua API returns several values (e.g. gui.get_type, gui.new_texture, buffer.get_metadata, collectionproxy.set_collection, sound.get_rms, window.get_size), ts-defold-types collapses the return to one @returns line. @defold-typescript/types instead types the return as a LuaMultiReturn<[…]> tuple, so each returned value is named in the type itself rather than in prose. The coverage test treats these as documented-by-type, not as a @returns regression.

Lua standard library reference category

The /api reference browser surfaces the Defold-engine namespaces plus a separate Lua standard library category for the pure-Lua / LuaJIT surfaces Defold documents (base, bit, math, os, string, table, coroutine, debug, io, package). Their TypeScript types come from the lua-types dependency the lua-stdlib-globals goal adopted (lua-types/special/jit-only.d.ts for bit, lua-types/core/global.d.ts for the base globals, lua-types/core/debug.d.ts and lua-types/core/io.d.ts for debug/io, and lua-types/core/modules.d.ts for package) and are wired into every script kind via the LUA_STDLIB_REFERENCES triple-slash directives in regen.ts — @defold-typescript/types does not re-emit them as generated namespaces (a duplicate declare namespace bit would collide, and the base globals are top-level globals, not a base.* namespace). The category is docs-only: a dedicated LUA_STDLIB_MANIFEST vendors the same ref-doc JSON SYNC_MANIFEST carries, but the docs-site is the only consumer; regen.ts / MODULE_MANIFEST never read it, so no generated/<ns>.d.ts is produced. The topbar's "Lua standard library" link leads to /api/base; the per-namespace page leads with a lua-types provenance note.

Where ts-defold-types is arguably cleaner

One deliberate trade-off runs the other way, on the elements @defold-typescript/types has no hand-authored TypeScript body for. There its @example block extracts the ref-doc examples field verbatim into a single ```lua fence — including the example's leading prose sentence (e.g. "How to create and initialize a buffer"), which then sits inside the code fence and is not valid Lua. ts-defold-types keeps the fence pure by putting that prose on the @example line itself.

This is the documented slice-4 decision: the ref-doc ships the prose and the code as one examples HTML blob, so the untranslated path keeps the sample intact and accepts a prose line inside the fence. Hover still renders the sample; the prose reads as a leading comment. Reversing it for that path is out of scope for the parity work.

A translated element does not take that path. Its blob is split into the examples it actually holds, each emitted as its own @example with a ```ts fence and the prose between them left outside the code — so an element documenting three examples ships three blocks you can copy one at a time.

Which surface fits your project

Both surfaces cover the same symbols, so this comes down to which documentation shape you want in your editor:

  • Reach for @defold-typescript/types if you want Markdown-rendered hovers, dash-style @params that editors lay out as a definition list, multi-line docs that stay aligned to the JSDoc grid, multi-value returns typed as a named LuaMultiReturn tuple, and branded constants that stay nominally distinct.
  • Reach for ts-defold-types if its one doc-quality edge matters to you: a pure @example fence with the prose kept out on the @example line.

This is your call, not a verdict — pick the trade-off that reads best for how you work.

On this page