Closed dylans closed 7 years ago
This should be converted into an epic with decomposed issues.
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.
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.
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.
So to keep this moving, here are my IA nice-to-haves:
*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'
So here are the decision points that I have so far:
typedoc
as our in-code documentation standard?FWIW, my votes are: yes, yes (provided we strip comments when building a release).
The argument against the second point (examples being documented inline for a few reasons) would be:
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...
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?
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..
@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. :)
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.
Setup workflow to generate API docs for Dojo 2 packages. Things to consider: