Move documentation to JSDoc

[sasha240100]

There is a JSDoc support for Readme.io - link here

I'd like to see it working with this project. How about moving docs there? It will be easier to maintain them.

Version:

• v2.x.x
• v1.x.x

Issue type:

• Bug
• Proposal/Enhancement
• Question
• Discussion

---

Tested on:

Desktop

• Chrome
• Chrome Canary
• Chrome dev-channel
• Firefox
• Opera
• Microsoft IE
• Microsoft Edge

Android

• Chrome
• Firefox
• Opera

IOS

• Chrome
• Firefox
• Opera

[hirako2000]

Swagger is actually more suited for RESTful APIs than for documenting libraries.

[hirako2000]

What about using JSDoc and push the generated doc to surge?

[sasha240100]

@hirako2000 Maybe use some integrations to use it for library API ?

[hirako2000]

@thejmazz , what do you think?

[thejmazz]

I don't think swagger is useful here, as @hirako2000 mentions - it is for documenting REST APIs.

It does seem very useful to have HTML documentation generated from code comments. JSDoc is great, and has a bunch of to-markdown, to-html tools. Maybe something like typedoc would work as well.

I'm curious how whs-specific features (e.g. "this component is compatible with module x", or "module y requires the position and rotation properties on the component") could be generated in an automatic way.

[hirako2000]

I don't think generated doc is all that useful right now.
probably better put some effort in typings, which give an incentive to provide human readable comment to functions and properties since they are exposed for typescript users.

I suggest we close this for now. provide clearer doc in readme.io where appropriate, more examples & some guides.

The source code ultimately is needed for understanding the core logic to extend certain components and create modules.

[hirako2000]

Progress on issue #189