Generate API Documentation, like TypeDoc

[samreid]

In phetsims/scenery#1464, @marlitas and I discussed writing and generating diagrams to depict the codebase. @pixelzoom expressed the concern that manually created diagrams could get out of date easily. @marlitas and I looked at using WebStorm to automatically (or with minimal manual effort) generate diagrams, and we also discussed automatically generating HTML documentation, which can show things like type hierarchy, composition, etc. And since it is more automatic, it may be easier to keep in sync (though would not replace well-designed and maintained diagrams).

I opened this issue here since built HTML documentation is a build artifact that will depend on multiple repos, and we may wish to version it like we version distributable JS files.

@marlitas and I looked at the spec https://tsdoc.org/ and one tool for generating docs: https://typedoc.org/. We tried rendering the docs for scenery and it did pretty well with type hierarchies and type parameters:

But not so good at mixins (but it says if you use idiomatic mixins it will support that TypeStrong/typedoc#979 )

In experimentation, I also found a way to get scenery docs to link to e.g., axon docs. Here is an example from scenery Node docs:

It correctly links to axon typedoc. This HTML documentation was generated using:

npx typedoc js/main.ts ../scenery/js/imports.ts 

After I had adjusted axon/main like so:

Index: js/main.js
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/js/main.js b/js/main.ts
rename from js/main.js
rename to js/main.ts
--- a/js/main.js	(revision 7f935b54b7fae05a35a0bc73e420c27cf4641e71)
+++ b/js/main.ts	(date 1666732131524)
@@ -7,34 +7,33 @@
  * @author Jonathan Olson <[email protected]>
  */
 
-import './animationFrameTimer.js';
-import axon from './axon.js';
-import './BooleanProperty.js';
-import './CallbackTimer.js';
-import './createObservableArray.js';
-import './DerivedProperty.js';
-import './DynamicProperty.js';
-import './Emitter.js';
-import './EnumerationDeprecatedProperty.js';
-import './MappedProperty.js';
-import './Multilink.js';
-import './NumberProperty.js';
-import './PatternStringProperty.js';
-import './Property.js';
-import './PropertyStateHandler.js';
-import './propertyStateHandlerSingleton.js';
-import './PropertyStatePhase.js';
-import './stepTimer.js';
-import './StringProperty.js';
-import './Timer.js';
-import './TinyEmitter.js';
-import './TinyForwardingProperty.js';
-import './TinyOverrideProperty.js';
-import './TinyProperty.js';
-import './TinyStaticProperty.js';
-import './UnitConversionProperty.js';
-import './units.js';
-import './validate.js';
-import './Validation.js';
-
-export default axon;
\ No newline at end of file
+export { default as animationFrameTimer } from './animationFrameTimer.js';
+export { default as BooleanProperty } from './BooleanProperty.js';
+export { default as CallbackTimer } from './CallbackTimer.js';
+export { default as createObservableArray } from './createObservableArray.js';
+export { default as DerivedProperty } from './DerivedProperty.js';
+export { default as DynamicProperty } from './DynamicProperty.js';
+export { default as Emitter } from './Emitter.js';
+export { default as EnumerationDeprecatedProperty } from './EnumerationDeprecatedProperty.js';
+export { default as MappedProperty } from './MappedProperty.js';
+export { default as Multilink } from './Multilink.js';
+export { default as NumberProperty } from './NumberProperty.js';
+export { default as PatternStringProperty } from './PatternStringProperty.js';
+export { default as Property } from './Property.js';
+export { default as ReadOnlyProperty } from './ReadOnlyProperty.js';
+export { default as PropertyStateHandler } from './PropertyStateHandler.js';
+export { default as propertyStateHandlerSingleton } from './propertyStateHandlerSingleton.js';
+export { default as PropertyStatePhase } from './PropertyStatePhase.js';
+export { default as stepTimer } from './stepTimer.js';
+export { default as StringProperty } from './StringProperty.js';
+export { default as Timer } from './Timer.js';
+export { default as TinyEmitter } from './TinyEmitter.js';
+export { default as TinyForwardingProperty } from './TinyForwardingProperty.js';
+export { default as TinyOverrideProperty } from './TinyOverrideProperty.js';
+export { default as TinyProperty } from './TinyProperty.js';
+export { default as TinyStaticProperty } from './TinyStaticProperty.js';
+export { default as UnitConversionProperty } from './UnitConversionProperty.js';
+export { default as units } from './units.js';
+export { default as validate } from './validate.js';
+export { default as Validation } from './Validation.js';
+// export { default as WebGLBlock } from './display/WebGLBlock.js';

I'm also seeing prior attempts at JSDoc-style HTML doc generation in:
phetsims/chipper#411
phetsims/scenery#499

Also note that for PhET-iO, we transpile TS=>JS then run jsdoc on the transpiled code to generate those docs. Generating type-aware docs for that step would be even better. Tagging @zepumph since he has overlapped with this part.

This also relates to the POSE grant and our open source ecosystem since publicly available code documentation would be useful to the community.

[samreid]

I'm also seeing some generated HTML docs at http://phetsims.github.io/scenery/doc/. Tagging @jonathanolson so he is aware of this issue.

[samreid]

Dot has a more complete rendered API docs example: http://phetsims.github.io/dot/doc/#dimension2

[marlitas]

I think TypeDoc is a great way to make our documentation more readable and accessible for the future, but I'm not sure it solves a type hierarchy tree/ diagram as @pixelzoom had mentioned in phetsims/scenery#1464. It definitely helps but it doesn't seem to provide a full overview of the hierarchy structure... perhaps that's enough though?

[samreid]

I agree that the API docs discussed here (while they show some aspects of hierarchy and composition) are not as clear as manually designed diagrams like https://github.com/phetsims/scenery/blob/master/doc/layout-implementation-notes.md

[pixelzoom]

Imo this is totally unncessary at the moment. And we've gone way off in the weeds on phetsims/scenery#1464.

[samreid]

I wonder if the proposal for mixin type declarations in phetsims/chipper#1356 would help with TypeDoc generation for them?

[samreid]

After the changes in phetsims/tasks#1132, this command ~/phet/root/projectile-data-lab$ npx typedoc --entryPointStrategy expand js ../scenery/js/imports.ts is generating our best type docs ever:

And here is a mixin from scenery: