Description
Greets folks,
I spent ~12 hours over the weekend thoroughly updating ESDoc in a fork that majorly improves the core functionality. Here are some of the advancements:
- Supports latest Babylon parser w/ all plugins allowing any edge / ES7 code to be parsed.
- Updated all dependencies to the latest and removed unnecessary ones.
- Removed all unnecessary code and dependencies like the esdoc web site that was previously embedded.
- Removed all local scripts in favor of integrating typhonjs-npm-build-test which provides standarized build / deployment tooling; note for development only Node 5+ is now required taking advantage of flat packages.
- All tests now produce coverage of the ES6 codebase directly.
The biggest advancement of course is the switch to Babylon for parsing. One should now be able to fully parse any ES6+ / edge / ES7 code as all plugins of Babylon are enabled by default. That doesn't mean the edge / ES7 AST is parsed for inclusion of data into documentation generated, but future work can now support for instance flow typing.
To test out this new effort please include the following in package.json:
"devDependencies": {
"esdoc": "git+https://git@github.com/typhonjs-node-esdoc/esdoc.git"
}
For the time being to link directly from Github the transpiled out/src/ code is committed to the repo. If a permanent fork moves forward with a release on NPM then the transpiled code will simply be removed from the repo as it will be generated in the publish / release process.
There is a branch made before the Babylon switch that has the latest espree version.
@h13i32maru please respond sooner than later and let's get a discussion going on whether I can be added as a collaborator to ESDoc and upstream this effort. The last thing I want to do is split the ESDoc community, but forward progress is important as well since ESDoc has clearly stalled. I know you mentioned you are still passionate about ESDoc, but please once again consider adding outside collaborators who can move it forward in your general absence.
I certainly want to respect in every way your effort with ESDoc. I've learned so much from your effort from how to publish ES6 NPM modules to the importance of providing a plugin architecture for a successful project! I do want to point out though that a successful open source project often takes a community and that it can be hard for one person to do it all. You were a great starter and architect of ESDoc, but the effort now needs debuggers and finishers - here is a basic blog post discussing this dynamic.
I know that communication issues due to language concerns will remain a difficulty and thus trusting outside collaborators is challenging.
If it is decided that a fork is more appropriate I will continue to advance my version of ESDoc and eventually it will be non-compatible especially from a plugin perspective which is something I'm really going to pay attention to in trying to work out a compatible solution. It should be noted that all TyphonJS repos / efforts are licensed under MPLv2. I'll fully indicate where the fork originated and give all credit that is due.
If we can find a way to have me involved directly in ESDoc as a collaborator I'd be glad to drop my fork and upstream everything.
Thanks for your consideration and I look forward to making ESDoc the premiere documentation tool for Javascript.