API references from source comments

A comment in a directory listed in js_source_paths has more than one reader, and they do not agree:

• Descriptions render as reStructuredText. The [text](/path/index.md) form used elsewhere comes out literally, with only the bare URL autolinked. Write the link as a role instead:

  :doc:`Places </browser/places/index>`
  

  A Markdown code span such as `forceForeground` renders as code, because docs/jsdoc-plugins/convert-descriptions-to-rst.mjs doubles its backticks. |name| is a substitution reference, and an undefined one fails the build rather than warning.

• A @param description renders as one paragraph. sphinx-js replaces every newline in one with a space, so a list or a heading written inside a parameter’s description arrives glued to the parameter above it. Structure belongs in the function’s own description, which keeps it.

• Write TypeScript types as TypeScript wants them. docs/jsdoc-plugins/accept-typescript-types.mjs passes predicates, generics, indexed access, tuples, arrow and import() types through to the page verbatim, though not as links.

• jsdoc keeps prose written after an @type tag, on the same line or below it, but logs a warning claiming it will ignore it. Put the prose above the tags to keep the build log quiet.

• Give @typedef a type – @typedef {object} Name – or jsdoc takes the first { in the prose under it as the type and logs a build ERROR.

• A documented default value renders, so [options.animate=true] is a claim about the code. Write one only where the signature supplies that default, and describe a computed default in the prose instead, where it can be kept accurate.

• A destructured parameter’s documented name is printed in front of every property under it, so the name a comment invents for an options bag is part of the rendered API rather than a local choice. Call it options, whether the parameter is destructured or not, unless the function takes two bags or passes one through to another call; there, name it for the call it belongs to, such as loadOptions.

• @throws renders as a throws field carrying its type. On a class, though, js:autoclass takes parameters, return values and exceptions from the constructor only, so those tags render nowhere from the class’s own comment. A method that checks its own contract at runtime documents the check in @throws rather than in a parameter’s description.

Verify by reading the rendered HTML

A passing build proves little about a generated page. sphinx-js never reads jsdoc’s exit status, so a type jsdoc could not parse costs nothing visible, and make_sphinx_js_skip_missing_objects in docs/conf.py turns a directive that names nothing into a warning. Open the page under <objdir>/docs/html/ and count its member anchors (id="<Class>.<member>") against the source, then spot-check a signature. An unresolvable @see is the exception: it fails the build with 'any' reference target not found.

jsdoc_cache is unset, so a page that disagrees with the source is never a stale cache.

The build log already carries many Invalid type expression lines from across js_source_paths. Search it for your own file rather than counting.

Links and anchors

• {@link foo} renders as the code literal ``foo``, not a link: convert-descriptions-to-rst.mjs rewrites it, and [label]{@link foo} becomes ``label``. Use a role for a link.

• Only members get anchors, as id="Class.member", which is also the form a @see tag needs. Class#member does not resolve. Parameters get no anchors, so an option key inside a parameter list cannot be linked to.

Types jsdoc cannot parse

jsdoc parses types with catharsis, which rejects some spellings that accept-typescript-types.mjs does not pass through. Introduce a named @typedef and use that.

• ?T parses and loses its nullability. jsdoc records {?Console} as Console alone, where {Console|null} keeps both names, and sphinx-js renders only those names. tsc and eslint treat the two spellings the same, so only the rendered page shows the difference. Write {T|null} in any file with a generated page.

• An unparseable type on a member that does not render, such as an excluded _-prefixed member, costs only a log line, so the stronger annotation can stay there.

Members that render wrongly or not at all

• jsdoc cannot name #-private members. docs/jsdoc-plugins/skip-private-members.mjs keeps the shapes it knows off the page. A shape it misses aborts the whole build, either with More than one object matches the path suffix (the doclet takes the enclosing class’s name) or with a parsimonious ParseError on an empty name that mentions no file. Widen the plugin rather than the comment.

• An inline cast on a member expression yields a doclet named for the expression, so /** @type {X} */ (aTab.documentGlobal) written twice in one file collides with itself. docs/jsdoc-plugins/skip-type-casts.mjs keeps such doclets off the page.

• A @typedef gets no entry of its own, and a record type renders as Object. js:autoclass renders members only, so a typedef’s name shows as plain text and its @property rows appear nowhere. Name the keys in the parameter’s description when a reader of the page needs them.

• A subclass page shows only the subclass’s own members. sphinx-js does not pull inherited members in, so a thin subclass of a documented base renders an empty class. Document the base under its own name, with a redirects entry in docs/config.yml from the subclass’s old page, as UrlbarInput does.

• _-prefixed members, and an empty constructor entry, are kept off the page with :exclude-members:.

Shapes that need a different directive

• export const Foo = new _Foo(); renders as class _Foo() with _Foo.method anchors. @alias Foo on the class’s doc comment gives the page the name callers use. A plain export class Foo needs no tag.

• export const Foo = { … } is not a class: an undocumented object literal yields nothing for js:autoclass to find, and documenting it gives a heading that reads as a class with an empty constructor. Write one js:autofunction per member instead, since there is no automodule, or use a prose page with an API reference section. The anchors are Foo.member either way.

• An exported module function has global scope, so js:autofunction takes foo or <FileBasename>.foo. The bare name aborts the build with More than one object matches the path suffix "foo" as soon as anything in js_source_paths has a member of that name. Qualify every directive on the page with the file’s basename.

Adding a file to js_source_paths

• Measure the lint work first. The comment above js_source_paths asks that a listed path stay out of the valid-jsdoc and require-jsdoc sections of eslint-rollouts.config.mjs. A path leaves a section by being named in that block’s ignores. Add both entries and run ./mach lint -l eslint -f json <file>; the count follows the comments the file already has, mostly @param types they lack, and is often the bulk of the work.

• List a single file rather than a directory that also holds window scripts or tests, whose bare globals and duplicate local names trip https://github.com/pyodide/sphinx-js/issues/242.

• Head the generated page with the class’s name, such as ## Tabbrowser. The directive adds no heading, and without one the class has nothing to nest under in the menu. The menu follows document order, so a {toctree} placed below an in-page ## section lands inside that section.

Probing jsdoc directly

Print every doclet jsdoc produces for a file, which answers whether sphinx-js sees a member at all, how jsdoc recorded its type, and whether it has a name:

cd docs
../mach node ../node_modules/.bin/jsdoc -c jsdoc.json -X <path-from-docs>

node_modules is there once ./mach doc has run.