Skip to content

Use JSDoc to document configuration settings for converse.initialize

JC Brand edited this page Aug 31, 2020 · 1 revision

As part of the directory layout reorganisation, we can use the opportunity to also change how the documentation surrounding configuration settings is generated.

One of the main advantages of JSDoc is that the documentation lives with the code, which helps to understand the code as you're reading it and makes it easier to keep documentation up to date, since you don't have to remember to update the docs somewhere else.

As part of the new directory structure, we'll the configuration for each plugin to a config.js file inside the plugin folder.

In that file, we can then use certain JSDoc directives to generate configuration documentation for Converse.

For the default configuration, (at time of writing in src/headless/converse-core.js), we can use @typdef to define a new ConverseSettings type.

We can then use @property together with @default, @description and @example to document configuration settings in a similar manner as we're doing manually right now.

In the config.js files inside plugin folders, we can use @augments to indicate that these plugins are adding properties to the ConverseSettings type.