Documention is mostly inline...can we reformat and make more user-friendly?

[JustinGOSSES]

wellio.js doesn't have that much code but documenting it in a friendly manner might help more people understand its internals.

I've mostly used sphinx for documentation in Python. Sphinx has a JS version, but it is pretty heavy featured. Something small and light that looks pretty by default but isn't super powerful might be a better choice.

I've previously looked at : https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md

but I'm open to other options?

[dcslagel]

@JustinGOSSES,

Caveat: While I have documentation experience it is not with Sphinx nor with Javascript documentation.

Observations:

• I did a scan of the various tools available: Both Documentation.js and Sphinx.js look like solid choices. Both have been around for a while and are active with recent issue and pull request activity. Their licenses are ICS and MIT respectively.
• It is a plus for Sphinx.js that you have Sphinx experience.
• It looks like both Documentation.js and Sphinx.js are using JSDoc format underneath. The JSDoc format seems to be the most standard Javascript documentation format. So regardless of a tool decision, updating the code with JSDoc documentation style and tags has to be done as some point. https://www.npmtrends.com/documentation-vs-esdoc-vs-jsdoc-vs-sphinx-js https://jsdoc.app/about-getting-started.html

My 2 cents... It might be best to to do an iteration of revising the code comments to adopt the JSDoc standards and style as well as iterating the content before committing to documentation generation tool.

DC

[JustinGOSSES]

I tried documentation.js on another project. It is pretty easy to get started with but it seems JSDoc has a limitation that config files for it can't find functions that are module exports. As such, it will include those files in the documentation but you can't structure the order they appear or include additional information around where they appear. They only appear at the bottom of the documentation page in the order they're discovered in the source files, which is okay but not exactly ideal.

Hence, I'll try to do some research into non-Doc.js based documentation libraries that can handles functions that are module exports.

[JustinGOSSES]

Seems like pretty much everyone uses JSdoc based documentation for JS. Problem isn't quite as bad as first though though. Started to put in some JSdoc style function descriptions as described here https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md

Will add documentation build script to github actions eventually.

[dcslagel]

@JustinGOSSES,

If you could implement an example JSdoc documentation of one function in a Wellio.js project file and post it on a draft branch?

That would give me (and maybe others) a project template to update the other Wellio.js function documentation to JSdoc format.

DC

[JustinGOSSES]

I've added some documentation to the index.js file. and did an initial build. You can use that as example. None of the tests are documented yet.

Should be live here: https://justingosses.github.io/wellio.js/docs/

[dcslagel]

Great, I'll use the example going forward.

Thanks DC

[github-actions[bot]]

Stale issue message