Errors generating reference docs for v12 release

[rachel-fenichel]

Check for duplicates

• I have searched for similar issues before opening a new one.

Description

npm run docs fails with "Cannot find module 'ajv/dist/core'", which appears to be because of nrwl/nx#27683 (comment)

Manually installing ajv directly worked: npm i ajv. However, we don't want to depend directly on that package long-term and it should not be necessary since it is an optional dependency.

One of the ajv-validator maintainers said that this was probably an npm issue, because it works with yarn and pnpm.

Once api-extractor runs, there are three warnings:

Warning: dist/core/block.d.ts:545:8 - (tsdoc-undefined-tag) The TSDoc tag "@yields" is not defined in this configuration
Warning: dist/core/field.d.ts:92:5 - (ae-setter-with-docs) The doc comment for the property "size_" must appear on the getter, not the setter.
Warning: dist/core/field_input.d.ts:69:5 - (ae-setter-with-docs) The doc comment for the property "size_" must appear on the getter, not the setter.

Reproduction steps

Stack trace

Screenshots

No response

Browsers

No response

[rachel-fenichel]

Running log of issues + debugging:

There is also a regression in table cell appearance/escaping with the latest version of api-documenter due to a change in the 7.24.0 release of api-documenter. Our minimum version is set to 7.22.4, and I'm using 7.26.26 locally.

Explanation here

A fix is to pin the version of api-documenter to 7.23.28. I will do this in develop shortly for future work, but will directly install it locally for docs generation from master.

Pinning the version of api-extractor then causes the documentation to go funky because the incorrect version of api-documenter is specified for patch-package. See #6506 for an explanation of what patch-package is for and https://github.com/google/blockly/commits/develop/patches/%40microsoft%2Bapi-documenter%2B7.26.26.patch for the most recent change to the patch.

In general, this implies that we should set api-documenter to a fixed version that matches the patch, rather than a minimum version.

[maribethb]

I've pinned the version to a good version and fixed the patch. Remaining work here is to fix the use of @yields which is not a valid tsdoc tag.