cst
Generate documentation using JSDoc
Can I +1 this? I am writing a yeoman generator and need to rewrite existing files, and esprima/escodegen are failing me in terms of preserving original formatting. I really like the idea of using a single tool for both parsing and generating, but it is extremely difficult to get up and going given that the documentation for this project is so thin. The wiki examples are as basic as examples get, and I'm working with a file using es6 imports and augmenting the definition of an angular module. Surely a preliminary JSDoc parsing of your code would be better than nothing in the short term?
Also, the main graph for master indicates that activity in this project has fallen off in the last several months (since July). Are you guys still committed to making the initial milestone?
I really like the idea of using a single tool for both parsing and generating, but it is extremely difficult to get up and going given that the documentation for this project is so thin.
I can try to answer them or we can figure it out together and later document these stuff.
Surely a preliminary JSDoc parsing of your code would be better than nothing in the short term?
That would be great, but we would need to figure infrastructure for it i.e. where and how to post this, parsing and outputting the result is an easy part. Plus we would to implement responsible maintenance of that repo and site.
Personally, I'm skeptical about JSDoc, I find use-case examples and explanation for them more helpful.
Also, the main graph for master indicates that activity in this project has fallen off in the last several months (since July).
Right now it is all about figuring out if this tool has their niche, if people would like to use it. We know it works and works relatively well, but the question is in the community.
Are you guys still committed to making the initial milestone?
We can bump to 1.0.0 right now, version number is just a number at this point
@markelog Thanks for the response!
While I prefer to have as much documentation for a tool as possible, I do understand your limiting constraints on the subject. I also think use-case examples and explanation are helpful, but it's impossible to cover every single use case, and I consider that to be supplemental documentation. The API documentation is important to know how to use all aspects of the tool, so I hope you don't end up choosing one over the other. However, it seems that a decent compromise might be including a build task that will build the docs so that people who clone the repo locally can at least generate something. I'm finding myself clicking back and forth through files and scrolling up and down to see what methods are available and any pertinent documentation. I suppose, in the meantime, I can try to generate some local docs myself just to get me through my current project. Hopefully there won't be any significant issues and jsdoc will just work. 😋
Right now it is all about figuring out if this tool has their niche, if people would like to use it. We know it works and works relatively well, but the question is in the community.
Well, now you know that at least one person has chosen this tool over esprima/escodegen! I'm getting used to it the more I solve my use cases, but the questions I have around nuance would eat up an issue thread and I don't want to clutter the Issues with my problems. If you guys had a gitter channel I would totally join and talk the ears off of you all. 😇
Just a quick followup, I attempted to generate docs by cloning the repo and received some errors:
$ jsdoc src -r -d ~/cst
ERROR: Unable to parse /home/vagrant/cst/src/Parser.js: Unexpected token {
ERROR: Unable to parse /home/vagrant/cst/src/Traverse.js: Unexpected token Element
ERROR: Unable to parse /home/vagrant/cst/src/elementTree.js: Unexpected token Program
ERROR: Unable to parse /home/vagrant/cst/src/elements/Element.js: Unexpected token Program
ERROR: Unable to parse /home/vagrant/cst/src/elements/ElementAssert.js: Unexpected token Element
ERROR: Unable to parse /home/vagrant/cst/src/elements/Fragment.js: Unexpected token :
ERROR: Unable to parse /home/vagrant/cst/src/elements/ModuleSpecifier.js: Unexpected token :
ERROR: Unable to parse /home/vagrant/cst/src/elements/Token.js: Unexpected token :
ERROR: Unable to parse /home/vagrant/cst/src/elements/types/Program.js: Unexpected token Token
ERROR: Unable to parse /home/vagrant/cst/src/elements/types/utils/getFunctionParams.js: Unexpected token ElementAssert
ERROR: Unable to parse /home/vagrant/cst/src/plugins/BasePlugin.js: Unexpected token Program
ERROR: Unable to parse /home/vagrant/cst/src/plugins/scopes/Definition.js: Unexpected token Identifier
ERROR: Unable to parse /home/vagrant/cst/src/plugins/scopes/Reference.js: Unexpected token Identifier
ERROR: Unable to parse /home/vagrant/cst/src/plugins/scopes/Scope.js: Unexpected token Node
ERROR: Unable to parse /home/vagrant/cst/src/plugins/scopes/ScopesApi.js: Unexpected token Variable
ERROR: Unable to parse /home/vagrant/cst/src/plugins/scopes/ScopesPlugin.js: Unexpected token Program
ERROR: Unable to parse /home/vagrant/cst/src/plugins/scopes/Variable.js: Unexpected token Definition
ERROR: Unable to parse /home/vagrant/cst/src/utils/lines.js: Unexpected token :
ERROR: Unable to parse /home/vagrant/cst/src/utils/toArray.js: Unexpected token <
Additionally, it seems that almost none of the types have any documentation:
$ ll ~/cst
total 72
drwxrwxr-x 18 502 dialout 612 Nov 4 2016 ./
drwxr-xr-x 16 502 dialout 544 Nov 4 2016 ../
-rw-rw-r-- 1 502 dialout 2640 Nov 4 2016 Assignable.html
-rw-rw-r-- 1 502 dialout 2136 Nov 4 2016 Expression.html
-rw-rw-r-- 1 502 dialout 1712 Nov 4 2016 Expression.js.html
drwxrwxr-x 20 502 dialout 680 Nov 4 2016 fonts/
-rw-rw-r-- 1 502 dialout 1286 Nov 4 2016 index.html
-rw-rw-r-- 1 502 dialout 1619 Nov 4 2016 interfaces.js.html
-rw-rw-r-- 1 502 dialout 2182 Nov 4 2016 ModuleDeclaration.html
-rw-rw-r-- 1 502 dialout 1747 Nov 4 2016 ModuleDeclaration.js.html
-rw-rw-r-- 1 502 dialout 2071 Nov 4 2016 Node.html
-rw-rw-r-- 1 502 dialout 1669 Nov 4 2016 Node.js.html
-rw-rw-r-- 1 502 dialout 2628 Nov 4 2016 Pattern.html
drwxrwxr-x 4 502 dialout 136 Nov 4 2016 scripts/
-rw-rw-r-- 1 502 dialout 2127 Nov 4 2016 Statement.html
-rw-rw-r-- 1 502 dialout 1706 Nov 4 2016 Statement.js.html
drwxrwxr-x 5 502 dialout 170 Nov 4 2016 styles/
-rw-rw-r-- 1 502 dialout 2467 Nov 4 2016 types_ArrayExpression.js.html
ESDoc seems to have done a much better job, but it did have a few errors for several files. Most of those errors seemed to point to additions from ~~typescript~~ flow, specifically with syntax like import type Whatever from './Wherever';. Unfortunately, some of the most important stuff was still left out, such as docs for Element (though it pulled in the README which has some info for this class), Token, and the parse/generate methods. ESDoc looks to be the slight winner here, so I've at least got a lil' something to work with for the time being.
UPDATE: Used flow-remove-types to create a flow-less version of the src/ directory, re-ran ESDoc on that new directory, and beautiful, comprehensive documentation was created! There were only two file errors (in Parser.js and Scope.js) from ESDoc which appear to be related to the es6 splat operator, but everything else produced documentation. Hope this information is/will be useful for you guys! 😇
Well, now you know that at least one person has chosen this tool over esprima/escodegen!
Well, we have like 200K downloads in the month so you are not the only one :). Although most of those users are probably use jscs which uses the cst.
Hope this information is/will be useful for you guys!
You know we can make this a npm command and mention it in the docs, wanna send us a PR?
Sure, I may need to resolve the splat issue with the ESDoc maintainers, but let me take a look. Do you have a preference on whether the docs should be served up or just accessed from the file system?
Do you have a preference on whether the docs should be served up or just accessed from the file system?
Dealers choice :), not sure what kind of output would be
There is also https://github.com/documentationjs/documentation, and you can use "transform-flow-strip-types" by itself as a separate babel config?
