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
API References Documentation
Tests
Testing API references doc generation with different options
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 librarysrc/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 auserConfig
parameter of typeClientConfig
, 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
@internal
annotation, than exporting on a needed basis and taking the risk to not exporting really useful entities (seeClientConfig
above) which impacts the DXtypedoc-plugin-missing-exports
--excludeExternals --excludePrivate --excludeInternal
—excludeExternals
is the most important one, particularly with the plugintypedoc-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@internal
annotation is not currently used by could be in the future, so still good to set--excludeInternal
typedoc
as a monorepo with a merge/resolution of the final doc--entryPointStrategy packages
but doesn’t look like it does the job, so have to check it