Decide on API documentation generation workflow

[dylans]

Setup workflow to generate API docs for Dojo 2 packages. Things to consider:

• Will we do something similar to Leadfoot and DigDug ( https://github.com/SitePen/jsdoc-catalyst-theme and https://theintern.github.io/leadfoot/ )?
• Will we build API docs per package or one view for all packages?
• Will we set this up to automatically rebuild nightly? Per new tag? Manual only?
• Multiple version support?
• Host on GitHub or Dojo web site?
• Integration with other documentation (e.g. something like a reference guide or tutorials, demos, etc.)?
• Other things to consider?

[kitsonk]

This should be converted into an epic with decomposed issues.

[rishson]

TypeDoc? https://blog.cloudflare.com/generating-documentation-for-typescript-projects/

[kitsonk]

Some of us have looked at TypeDoc before... it has it challenges and isn't perfect, but it is something. On the other hand, I have been working in my spare time on something as well. There are a lot of other questions to answer too outside of just the tool we would use, like what the IA would be for it that we should determine what our requirements are and then see if the tooling can meet them.

[rishson]

I do think this is a possible area where we could have a standalone FOSS offering that is good docs for TS. Re ^ - if anything is shareable, then please do. I have previously thought of writing a node module that checks ts doc and can also be used in an IDE to provide boilerplate doc for a function. I guess we'd need to write a tslint custom rules as well.

[rishson]

I've had a quick look at the current ecosystem for ts docs. Apart from typedoc, there are lots of offerings that link TS to jsdoc and use the existing jsdoc ecosystem. This seems wrong, and typedoc seems preferable as the comments are just the comments because the types are in the codez. I notice that Cloudflare are about to open source their typedoc -> wiki toolchain so we could wait for that, or we could have a go at our own tsdoc offering.

[rishson]

So to keep this moving, here are my IA nice-to-haves:

1. use TS specific comments, i.e. TypeDoc style, not JSDoc
2. invoke by cli and generate docs per module, per project..
3. programatic API that can parse a module and provide access to type-enhanced docs for all the module's members
4. ability to validate existing module docs and list documentation failures, i.e. missing docs
5. ability to provide relative path urls in type-enhanced docs

*type-enhanced docs:

Given typedoc for a function:

/**
 * This is an awesome function that tells you how awesome you are (1-10)
 **/
function howAwsome(name: string, really?: WhackyModule): number {...}

the type-enhanced docs should be something like:

const myModule = docThing.parse(path/to/my/module);
const myAwesomeFuncDoc = myModule.functions.private.get('howAwesome');
//myAwesomeFuncDoc.comment would be 'This is an awesome function...'
//myAwesomeFuncDoc.sig would be 'function howAwesome(name: string): number'

treeGenThing.generateDocTree(docThing);
//myAwesomeFuncDoc.sig.params.get('really').toUri() would be 'path/in/generated /tree/to/WhackyModule'

[rishson]

So here are the decision points that I have so far:

• [ ] Do we use typedoc as our in-code documentation standard?
• [ ] Do we want to generate api doc only from our source, e.g. example usage of functions will be in the code?

FWIW, my votes are: yes, yes (provided we strip comments when building a release).

[dylans]

The argument against the second point (examples being documented inline for a few reasons) would be:

• It would require a change to the source for that file to add or fix examples, increasing the barrier to entry to add examples, and requiring a new release to add examples for that package
• How do you automate the testing of inline examples to make sure they work and don't regress?

[kitsonk]

I agree with @dylans... the API documentation should have some sort of merge/reference capability... e.g. "Here is an example for dojo-widgets/bases/createWidgetBase#id" that would get pulled in through the doc generation process...

[rishson]

So the 'examples' that I had in mind are similar to what you find on Javaland; 'good' (subjective) javadoc for an API, includes an explanation of the API and example usage. See flatMap here for what I was getting at.

These are not example usage to the extent that they proove the API to be correct, rather, they are syntactic examples of calling the API. I think that as a maintainer, you should be required to update the examples in the doc when you change the API. I don't think the example usage needs to be 'tested' as there is nothing but the API call (no mocks, instantiations etc).

Does this change your opinions at all?

[rishson]

I should note, that even in Javaland, API examples are pretty rare, and are only used when the API description needs further clarification. You could argue that you need to change your API if you have to provide examples..

[dylans]

@rishson I think your argument reinforces my point... any meaningful example should live elsewhere and be tested and linked/merged, and any example simple enough to consider including inline shouldn't be needed if we've done a decent job in defining the Dojo 2 APIs. :)

[dylans]

I believe this has all been decided on and we have a POC to cover this. We're going to collaborate with the TypeDoc team to improve TypeDoc, and leverage that within our website architecture.