Force esdoc to process non ES6 code #258

Closed
ibc opened this Issue Apr 2, 2016 · 13 comments

Projects

None yet

7 participants

@ibc
ibc commented Apr 2, 2016

I understand that esdoc is designed for ES6. And I code in ES6 as much as I can, but Node does not implement import.

I've read #168 but still don't know how to force esdoc to document something like this:

module.exports =
{
  /**
   * Main function of the module blablabla
   */
  doStuff: function()
  {
    // do stuff
  }
};

I don't think a plugin-feature may help here. Isn't there a "tag" or something that tells esdoc "please process this"?

@hmil
hmil commented Apr 3, 2016

Have you tried a solution based on string replacement as suggested here?

Also beware that ESDoc will not be able to find a name for the object you are exporting and therefore will not generate documentation. You must store the object in a variable for ESDoc to pick up its name.

@ibc
ibc commented Apr 7, 2016

Have you tried a solution based on string replacement as suggested here?

Yes. It works just in some specific cases.

Also beware that ESDoc will not be able to find a name for the object you are exporting and therefore will not generate documentation. You must store the object in a variable for ESDoc to pick up its name.

Clear. Thanks.

@typhonrt
Contributor

I understand that esdoc is designed for ES6. And I code in ES6 as much as I can, but Node does not implement import.

Just a quick note as I've moved all my NPM modules to ES6 and use ESDoc to document them. You do have to use Babel before publishing / distribution. I've created an all inclusive module that might help for documenting, testing, linting, transpiling, including prepublish detection / script runner for ES6 NPM modules here: typhonjs-npm-build-test.

@ibc
ibc commented Apr 13, 2016

You do have to use Babel before publishing / distribution

Why should I use Babel in my Node application if Node >= 4.0.0 already support lot of ES6? (yes, import is not supported).

@typhonrt
Contributor

yes, import is not supported

That's a good start for why Babel.. ;) It all depends. If you plan to publish on NPM then using Babel allows anyone consuming the module with any Node version. If you don't plan to publish or this app is for controlled / private usage where you can control the Node version then when Node has full ES6 support then certainly go for that.

I should also note that if you happen to use Gulp then having Babel available allows all your Gulp scripts to be created with ES6 as well by adding babel to the name of the gulp file: gulpfile.babel.js. Also with Babel installed you can use babel-node to execute NPM scripts and use ES6 for all your tests as well.

The module I posted does contain several other resources for a good test / build environment. The prepublish script runner support is handy as well.

@ibc
ibc commented Apr 18, 2016

In my case, my server-side Node app requires Node >= 4.0.0 (which is the LTS/stable Node version and already supports a good subset of ES6), so I don't need Babel at all to run my server. Of course I don't use import but require.

This is, I don't need Babel for my Node app to run so I won't refactor the whole code just to make it 100% ES6 and make esdoc happy, nor I'll require node-babel to run my app.

@typhonrt
Contributor

Yeah.. You don't want to use babel-node for running an app in production. It's fine for testing. IE you'd simply run a single NPM script to transpile then run. Just a FYI as it's easy and this would make your app run on any version of Node too. Babel is straightforward and ESDoc is really great. I'm releasing some really awesome ESDoc plugins improving the navigation on the left and adding interactive SVG / D3 source code and package dependency visualization graphs for NPM and JSPM managed code soon that extend ESDoc even further.

I'm doing a lot of AST modification for the above graph generation. I'll take a look at what things look like at the AST level when require is mixed with ES6 modules. It should get through the parser (Espree / ESTree) and maybe there could be a mod for ESDoc in the future, but it's a corner case for sure. I just checked with https://astexplorer.net/ and it looks like AST with mixed require / ES6 modules can be parsed. So it would be possible to create a plugin for ESDoc that could conceivably create the tags for ESDoc to understand. It's a bit of work though.. ;P

I do use require in a very few rare occasions for a couple of NPM modules where ES6 import hoisting is non-desirable.

@StephanBijzitter
StephanBijzitter commented May 11, 2016 edited

Babel is only needed when you write code that your target's environment cannot execute. As this is not the case, Babel should not even be an option here.

I have several private packages that use node 5.5, but ESDoc is breaking on module.exports = Something. The plugin suggested above does not work, for ESDoc crashes before it can be executed.

ESDoc is a package available on NPM, but it does not support Node. That is, to be blunt, absurd.

@h13i32maru

@ibc
ibc commented May 11, 2016

Basically ESDoc is not valid for Node applications regardless they are written in ES6 (plus require(), of course).

@typhonrt
Contributor

@StephanBijzitter

module.exports = Something

@ibc

Basically ESDoc is not valid for Node applications regardless they are written in ES6 (plus require(), of course).

Because both of those examples are CJS and not pure ES6! Mixing CJS whether that is module.exports or require will not work with ESDoc which is for pure ES6 documentation generation only.

ESDoc is a package available on NPM, but it does not support Node. That is, to be blunt, absurd.

This makes no sense as NPM doesn't dictate that all modules must work with all versions of Node. Simply using Babel on ES6 NPM modules before publishing makes things work on any version of Node.

I am not proposing anything off the beaten path when saying Babel is perfectly fine for publishing ES6 NPM modules (don't believe me read someone else's article):
https://booker.codes/how-to-build-and-publish-es6-npm-modules-today-with-babel/

The typhonjs-npm-build-test module I listed above contains all the dependencies and several NPM scripts that handle all the corner cases to easily publish ES6 NPM modules with documentation generated from ESDoc.

Practically all my NPM modules (~12 of 16) are written in pure ES6 using typhonjs-npm-build-test / Babel for transpiling via a script runner automatically which first runs ESLint, then tests, then Babel, before npm publish is run with a fix for the npm prepublish bug (npm/npm#10074). It indeed works rather well.

You can't complain when there are easy to use and standard solutions to solve ES6 NPM module publishing. To "be frank" it is "absurd" to refuse to use the appropriate tools or continue to be adamant in mixing CJS w/ ES6 and complain when things like ESDoc don't work.

@chadxz
chadxz commented Oct 22, 2016

I would like to use this tool, but would rather not have to add babel as a dependency of my project. There are reasons why I do not want to use babel, such as debuggability and cognitive overhead. On top of that, if node 6 supports the style of es6 that I am writing, I have very little incentive to want to bring in a heavy transpiler just to unlock the ability to use a specific documentation tool on my code.

It would be really nice if support for require() were considered.

@chadxz chadxz referenced this issue in chadxz/awry Oct 22, 2016
Open

Add API documentation #6

@adamjmurray

I'm having difficulty with this too.

I'm working on modern Node modules that use native ES6 support in Node 6+ (which is now the long-term-support version of Node encouraged for all Node developers to use: https://nodejs.org).

I don't want the added overhead and complexity of Babel just for documentation. I would like to use ESDoc, but for now it doesn't seem to be an option for me because it doesn't understand require() and module.exports.

I'd be happy to write more annotations in my ESDoc comments to give it the hints it needs to document my code, but this doesn't seem to be possible right now. For comparison, JSDoc has tags like @class and @function. JSDoc doesn't actually support most ES6 syntax yet, but I am able to make it work well enough by using these tags to explicitly document syntax structures it does not understand.

TL;DR - JSDoc currently works better for my native Node 6 / ES6 code, so I'll keep using that for now. However, I am interested in ESDoc and I'll reevaluate it periodically.

@h13i32maru
Member

Sorry for late reply.

I don't have plan to support require/module.exports. However you can use esdoc-node that is third party plugin for it. And you may solves your problems.

@h13i32maru h13i32maru closed this Dec 27, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment