JSDOC documentation

[raineorshine]

Try these and compare:

• https://github.com/documentationjs/documentation
• https://github.com/clenemt/docdash
• https://github.com/nijikokun/minami

[pushkov-fedor]

I've tried these today. docdash and minami - just theme templates for jsdoc generator output (https://github.com/jsdoc/jsdoc).
I didn't find configuration, but looks like documentation.js, out-of-the-box, doesn't work well with arrow function. Here's screenshots for isLeftSpaceClick function defined as arrow function, and as standard function


Bellow screenshots for standard jsdoc theme, minami and docdash

As you see, jsdoc also pastes source links and generates files for them
minami/docdash

What do you think? Maybe you have certain vision of tools and functions that doc generators should have?

[raineorshine]

I've tried these today. docdash and minami - just theme templates for jsdoc generator output (jsdoc/jsdoc).

Great!

I didn't find configuration, but looks like documentation.js, out-of-the-box, doesn't work well with arrow function. Here's screenshots for isLeftSpaceClick function defined as arrow function, and as standard function.

Yeah, it's close, just not generating the signature correctly. If you haven't done further research yet, I suggest searching the web, StackOverflow, and the documentation.js documentation to see if others have encountered this problem and if there are any solutions.

Bellow screenshots for standard jsdoc theme, minami and docdash

Nice! I like minami the best.

What do you think about hosting our documentation on https://readthedocs.org? Please look into this and see if it's compatible with documentation.js, and let me know what you recommend.

[pushkov-fedor]

About documentation.js and arrow function, it isn't a rocket science, so adding @kind function to JSDOC comment helps :)

documentation.js (https://github.com/documentationjs/documentation) doesn't support jsdoc (https://github.com/jsdoc/jsdoc) templates (minami, docdash), i found a couple of themes for documentation.js, but they look pretty ugly (https://github.com/giacomocerquone/documentationjs-themes-list). Actually they both work with JSDOC syntax, i think we can start with any of them and then just replace documentation.js with jsdoc or vice-versa.

readthedocs advices to use sphinx or mcdocs generators, they both are written on python. I tried to import doc, generated by documentation.js, but it didn't work. I'm sure there's a way to publish documentation/jsdoc generators output, but it needs some work and setup.
Also i'm a bit worried about ad banner on readthedocs's page, which i unsuccessfully imported from github :) https://documentation-test-for-em.readthedocs.io/en/latest/

Actually, both jsdoc and documentation.js generate html output. We can host it on github pages. Look here: https://pushkov-fedor.github.io/documentation-test/
Anytime we can move docs to hosting. What do you think?

[raineorshine]

About documentation.js and arrow function, it isn't a rocket science, so adding @kind function to JSDOC comment helps :)

That's unfortunate that it takes an explicit comment. It should be statically analyzable. If absolutely necessary, we could add an eslint rule to enforce @kind. It's not something most developers will think to add otherwise.

documentation.js (documentationjs/documentation) doesn't support jsdoc (jsdoc/jsdoc) templates (minami, docdash), i found a couple of themes for documentation.js, but they look pretty ugly (giacomocerquone/documentationjs-themes-list). Actually they both work with JSDOC syntax, i think we can start with any of them and then just replace documentation.js with jsdoc or vice-versa.

Maybe the more general question is, what does documentation.js offer that other document generators do not?

readthedocs advices to use sphinx or mcdocs generators, they both are written on python. I tried to import doc, generated by documentation.js, but it didn't work. I'm sure there's a way to publish documentation/jsdoc generators output, but it needs some work and setup.

Okay, might not be worth it then. We can always host a static documentation site on GitHub Pages as well.

What does readthedocs offer besides hosting compared to other solutions?

Also i'm a bit worried about ad banner on readthedocs's page, which i unsuccessfully imported from github :) documentation-test-for-em.readthedocs.io/en/latest

Yes, not ideal.

Actually, both jsdoc and documentation.js generate html output. We can host it on github pages. Look here: pushkov-fedor.github.io/documentation-test
Anytime we can move docs to hosting. What do you think?

Yes! I like that plan!

[raineorshine]

Just added JSDoc comments to all functions btw in 1503ee2, along with an eslint rule to require them from now on.

[pushkov-fedor]

Just added JSDoc comments to all functions btw in 1503ee2, along with an eslint rule to require them from now on.

Awesome! I've noticed it during yesterday rebase :)

About jsdoc and documentationjs. I think jsdoc is a better option, it has strong, very active repo, detailed documentation unlike documentation.js., cool themes, an ability to configure itself from configuration file and to add source code inside generated documentation files.
It doesn't generate Markdown and JSON outputs like documentationjs does, but i think if we need such outputs, we will handle this with additional tools. A
What do you think?

Actually i'm a bit confused of the fact that documentation.js declares support of modern javascript, but doesn't generate correct arrow function documentation without @kind param. I've searched the web today and haven't found any solutions or even issues about this. Maybe i should try again

[raineorshine]

About jsdoc and documentationjs. I think jsdoc is a better option, it has strong, very active repo, detailed documentation unlike documentation.js., cool themes, an ability to configure itself from configuration file and to add source code inside generated documentation files.

Great! This is exactly the sort of explanation and recommendation I was looking for.

It doesn't generate Markdown and JSON outputs like documentationjs does, but i think if we need such outputs, we will handle this with additional tools.

Yup, I don't foresee a need for Markdown or JSON output in the immediate future.

Actually i'm a bit confused of the fact that documentation.js declares support of modern javascript, but doesn't generate correct arrow function documentation without @kind param. I've searched the web today and haven't found any solutions or even issues about this. Maybe i should try again

Yes, that seems odd! You can always ask on StackOverflow if you can't find anything. People are usually pretty quick to respond there.

[raineorshine]

Let's put the documentation output in the /docs folder. It looks like I'll have to rename dev to master in order for GitHub to pick it up.

https://github.blog/2016-08-17-simpler-github-pages-publishing/

[pushkov-fedor]

Raine, please pardon my rush, i totally forgot about typescript part of em. I've done small research during these 2 days. My favorite JSDoc doesn't go well with it. I've dived deeper in documentationjs. It still has awful documentation (it's a little a funny :) ), but i succeeded in running it through em's typescript files. It works as we needed (generates @param and @returns from code), but goes bad with combination of js and ts files.
I found TypeDoc. It gets along with js and typescript and has a cool default theme. Documentation also pretty good.

There's amazing tool Docusaurus which allows to create astonishing and detailed documentation site. But it uses markdown format and needs from us much more time than generators. https://docusaurus.io/ So i just leave it here for your information.

Also i would like to clarify your view of whole documentation epic and its purpose. We can run generator through all files, generate description, param, return and group results by folder name (e.g. utils, reducers). For the most commonly used functions we can write examples part by hand. Also enable all links from documented function to all imported modules. So developers could easily find out what the function does and what functions it depends.
What about components? Some of them have plenty logic inside yourself. Explaining what happens there could take time. We can just detailed describe component function itself and its surrounding functions (like beginDrag, endDrag in Thoughts.js).

Thank you!

[raineorshine]

Raine, please pardon my rush, i totally forgot about typescript part of em. I've done small research during these 2 days. My favorite JSDoc doesn't go well with it.

Does it not work at all? Or are there problems? If so, briefly describe the problems.

I've dived deeper in documentationjs. It still has awful documentation (it's a little a funny :) ), but i succeeded in running it through em's typescript files. It works as we needed (generates @param and @returns from code), but goes bad with combination of js and ts files.

What does "go bad" mean? Please explain in detail.

I found TypeDoc. It gets along with js and typescript and has a cool default theme. Documentation also pretty good.

Yes, this looks quite good. I somewhat prefer the left sidebar of minami, but the main panel and details are good.

There's amazing tool Docusaurus which allows to create astonishing and detailed documentation site. But it uses markdown format and needs from us much more time than generators. docusaurus.io So i just leave it here for your information.

Thanks, interesting. Yeah for now let's just stick with tools that can generate docs from JSDOC comments.

Also i would like to clarify your view of whole documentation epic and its purpose. We can run generator through all files, generate description, param, return and group results by folder name (e.g. utils, reducers).

Yes, I'm glad you asked. I'm sorry if I misrepresented the scope of this epic right now. JSDOC generation is a low-hanging fruit. Since we're using JSDOC comments anyway, this is an easy way to get something basic up. When we have a public API, that will require detailed documentation. However detailed documentation of the internal API is very low priority right now. We should be focusing on bugs, features, testing, refactoring, and preparing for the beta over detailed internal docs.

For the most commonly used functions we can write examples part by hand. Also enable all links from documented function to all imported modules. So developers could easily find out what the function does and what functions it depends.

This will be a good step later on down the road.

What about components? Some of them have plenty logic inside yourself. Explaining what happens there could take time. We can just detailed describe component function itself and its surrounding functions (like beginDrag, endDrag in Thoughts.js).

If there are particularly confusing parts of components, I am open to refactoring and/or documenting their usage. This should be done on an as-needed, ad hoc basis for now rather than a systematic documentation push.

[pushkov-fedor]

About jsdoc. It could be used for typescript files but it needs hand-written @param, @returns tags. Also just parsing typescript files with JSDOC comments needed additional configuration and babel plugins.

It's a pretty old comment but i didn't find ant solutions for this task.

I coudn't run documentationjs through whole project, it started to resolve all imports and failed on .tsx files. Authors recommend to use --shallow flag for typescript files. I found this information in one of their issues also like i found there necessary flag --parse-extension for parsing ts files. They didn't mention about it in their docs.

Extra information
TypeDoc and JSDoc doesn't support export default (args) => {}. We have to declare arrow function (const fun = () => {}) and then export it by default (export default fun)

We need to paste @kind function or @function in comments of arrow function for JSDoc and documentationjs generators. TypeDoc are pretty clever to understand it without any additional tags.

I like the fact that TypeDoc also generates pages for custom types and interfaces, documentationjs doesn't.


And creates links to these pages on function documentation pages

I runned documentationjs through components directory and i don't know why it includes "addMissingProtocol","DEFAULT_SEARCH_LIMIT" etc. Needs additional configuration

Result for typedoc

Here's result for AppComponent.tsx. I like that it generates source links to Github files inside page, documentationjs doesn't

Also generated documentation is pretty detailed

How it looks for documentationjs

I'm sure that there's some moments like additional configuration, plugins etc about all generators that we don't know. But any deeper investigation needs extra time and i think it's better to choose one and dive into it.
I like the fact that TypeDoc allows to create cool, detailed documentation for ts/js/tsx files out-of-the-box and without any configuration. For other tasks like grouping files by directory name or some custom label, i can go to their docs

What do you think about it? Please tell me if i forgot to check some part of desired functionality for generator.

[raineorshine]

About jsdoc. It could be used for typescript files but it needs hand-written @param, @returns tags.

That's disappointing. Seems like someone would have implemented that!

Also just parsing typescript files with JSDOC comments needed additional configuration and babel plugins.

Sure, but that in itself is not a problem assuming it works.

It's a pretty old comment but i didn't find ant solutions for this task.

Good to know.

i found there necessary flag --parse-extension for parsing ts files. They didn't mention about it in their docs.

Good find!

Extra information
TypeDoc and JSDoc doesn't support export default (args) => {}. We have to declare arrow function (const fun = () => {}) and then export it by default (export default fun)

I'm okay with that. In fact, I prefer it. Maybe we can get linter rule to enforce that.

We need to paste @kind function or @function in comments of arrow function for JSDoc and documentationjs generators. TypeDoc are pretty clever to understand it without any additional tags.

Okay, TypeDoc definitely has the advantage here, although this is less egregious than having to explicitly specify @param and @return.

I like the fact that TypeDoc also generates pages for custom types and interfaces, documentationjs doesn't.
And creates links to these pages on function documentation pages

Yes! Very nice.

I runned documentationjs through components directory and i don't know why it includes "addMissingProtocol","DEFAULT_SEARCH_LIMIT" etc. Needs additional configuration

Yes, that's strange. Does JSDOC have the ability to separate by module? Perhaps with @module? (No need to answer this if we decide to go with TypeDocs.)

Also, is there any way to get TypeDocs to group by module e.g. components rather than list the full path src/components/Component? It's not ideal repeating the full path on each line.

Here's result for AppComponent.tsx. I like that it generates source links to Github files inside page, documentationjs doesn't
Also generated documentation is pretty detailed

Very nice!

I'm sure that there's some moments like additional configuration, plugins etc about all generators that we don't know. But any deeper investigation needs extra time and i think it's better to choose one and dive into it.

Sounds good.

I like the fact that TypeDoc allows to create cool, detailed documentation for ts/js/tsx files out-of-the-box and without any configuration. For other tasks like grouping files by directory name or some custom label, i can go to their docs

👍👍👍

What do you think about it? Please tell me if i forgot to check some part of desired functionality for generator.

🎉 TypeDocs! 🎉

Thanks for your thorough research, clear explanations, and indicative screenshots. Great work.

[raineorshine]

I would suggest adding an npm script docs that generates the documentation in the /docs folder. Then I can enable GitHub pages.