Optimise API documentation generation

[aurelticot]

API References Documentation

Tests

Testing API references doc generation with different options

missing exports plugin	true	true	true	true	false	false
excludeExternals	false	true	false	false	false	true
excludePrivate	false	false	true	false	false	true
excludeInternal	false	false	false	true	-	-
Nb files	1121	551	1121	1121	150	150
Nb classes	223	67	67	67	27	27
Nb enums	36	32	32	32	7	7
Nb interfaces	814	412	412	412	92	92
Nb modules	45	37	37	37	21	21
Has missing Verida	Probably not	Probably not	Probably not	Probably not	Probably	Probably
Has non-Verida	Yes	Apparently not	Yes	Yes	No	No
Has duplicates	Yes	Yes	Yes	Yes	Probably not	Probably not
Has linked references	No	No	No	No	No	No
Comment				Nothing annotated as @internal anyway

Problems

Documentation missing Verida entities

The plugin typedoc-plugin-missing-exports generates the documentation of "internal" entities (entities that are not exported by the entry points of the library src/index.ts). These entities are marked as “Internal” in the documentation. This plugin has the drawback to basically generate the doc of everything it finds.

As there are useful entities, needed by the developer, which should be documented but are currently not exported by the entry points.

Example the constructor of the Client class takes a userConfig parameter of type ClientConfig, this type is not exported but it would be useful for building the client config in a variable on the side.

If we properly export the needed types, we would not need this plugin.

No resolution of the reference and Duplicates

As a monorepo, entities are exported by modules and imported by others.

The documentation of the consuming module should reference the entity from its original module (having a link to the corresponding file). But it’s not the case, it’s actually creating duplicates in its own module documentation and linking these duplicates instead.

Note that without the plugin missing-exports there are no such duplicates, but there is no link to the referenced entity, which is very annoying.

typedoc needs a specific configuration in monorepo, and consolidate all the package docs to resolve who consume what.

Recommendations

• Properly export all the entities from the entry points of each module
  • As a library it’s a good practice, even if some entities are not to be used directly by the developer, some edge cases may require the developer to use it, for instance to assert a type.
  • Better to export all entities by default and restrict the documentation with the @internal annotation, than exporting on a needed basis and taking the risk to not exporting really useful entities (see ClientConfig above) which impacts the DX
  • Eventually remove the plugin typedoc-plugin-missing-exports
• Use the CLI options --excludeExternals --excludePrivate --excludeInternal
  • The —excludeExternals is the most important one, particularly with the plugin typedoc-plugin-missing-exports as it prevents documentation third-party modules (axios, etc.)
  • --excludePrivate is a good practice even though it doesn’t reduce the number of doc file
  • The @internal annotation is not currently used by could be in the future, so still good to set --excludeInternal
• Configure typedoc as a monorepo with a merge/resolution of the final doc
  • Looks like our current commands is doing it with --entryPointStrategy packages but doesn’t look like it does the job, so have to check it
  • May need to upgrade the version of the dependencies and update the configuration as per typedoc examples. But first tests while writing down this ticket were not successful