Config values aren't in the docs

[zspriggs]

Location

No response

Type

• Text
• Image or Gif
• Other

Suggested content

The variables in config.ts aren't documented anywhere. There are explanatory comments on the file, but API documenter just generates this minimal page for the reference docs which doesn't include any of the object members.

config is exported as an object, and it seems like API documenter can't document the members of that object. The Config interface could be exported in addition to this, which theoretically should make the members visible to API documenter, but I don't know what other consequences that would have.

This is important to include somewhere in our documentation because

• The config object is explicitly stated to be “all the values on Blockly that we expect developers to be able to change” so developers need some way to know that those values exist.
• The lack of information can lead to confusion

To resolve this we could:

• Fix the setup so that the API docs include info about config members.
• Move or repeat the member description in a @remarks tag (or something similar) so that the info is recorded on the API page. This is probably a little unconventional but at least it improves the visibility of the information.
• Add a document describing how to change these config variables to the guides. This is probably a bad option, since although these config values are changeable, they are limited and I wouldn’t expect that many developers actually want/need to change them. So it feels more suitable to have this sort of thing in the API docs than the guides.

This is sort of a proposal for a solution to #2217, but I’ve filed it as a separate issue because I think there is a broader discoverability problem that's a bit outside of the scope of that issue.

Additional context

No response