jsdocer plugin testbed
Olov Lassus
The annotater plugin was created to make it really easy to capture annotations (see bitwiser for a simple usage). If it's not sufficient for everything jsdocer must do then just take a look at how its implemented (Comments.split is the key). It uses Shaper.traverseTree like most shaper plugins.
/Olov
Michael
This is very interesting. Having worked just a little with the
Narcissus AST directly, I can definitely see how much easier it is to
use the Shaper API on top of it. You've created a great piece of
software that should make it possible, even enjoyable, for anyone to
rework JavaScript source code in whatever way they please.
One critical requirement for JSDoc however is that it be runnable
under Rhino (as well as node, in version 3). I've been able to force
Narcissus to run under Rhino, with a Rhino-Require shim, plus a minor
tweak to their core code, but I wondered if you had any interest or
experience in this area?
Regards,
Michael
On May 13, 7:34 pm, Olov Lassus <olov.las...@gmail.com> wrote:
> I commited a jsdocer plugin testbed to shaper containing the code that was discussed on the nug list <http://librelist.com/browser//nug/2011/4/30/porting-jsdoc-to-node/#b9...> together with an annotater pass that prints any kind of /** ... */ annotation with its corresponding node. Michael hope that this is of help to you.
Olov Lassus
> You've created a great piece of
> software that should make it possible, even enjoyable, for anyone to
> rework JavaScript source code in whatever way they please.
I need to save that quote somewhere. It is indeed the goal of Shaper.
Right now plugins reside under the Shaper directory, in the future it will also be possible to run plugins that reside in your local JS project. This could be useful for one-off project specific Shaper-snippets. There will also be support for a project-level Shapefile (or .shaper, or something else) that specifies the plugin pipeline.
> One critical requirement for JSDoc however is that it be runnable
> under Rhino (as well as node, in version 3). I've been able to force
> Narcissus to run under Rhino, with a Rhino-Require shim, plus a minor
> tweak to their core code, but I wondered if you had any interest or
> experience in this area?
Sure. Here's an excerpt of the README (which need to be merged with jsshaper.org by the way):
JSShaper is designed to run from the command line. It should be
possible to use with the following JS shells:
js: recent versions of Mozilla SpiderMonkey
d8: Google V8 debug shell
node: Embedded V8 with lots more
It doesn't work with the JavaScriptCore jsc shell since it has no
native read function.
---
The prerequisites for getting a JavaScript shell working with Shaper is argument passing and native load and read functions. load for loading and executing another piece of JS code, read for reading a textfile to a string. For node, require and readFileSync are used instead.
I didn't try Shaper with Rhino before, so I downloaded Rhino 1.7R3 and gave it a try. It seems to lack a native read function (or rather I found no), so you need to add that. It has argument passing and a native load though. Right now it bails out in Narcissus - Rhino doesn't seem to like Narcissus's technique of eval:ing constants. You can work around that temporarily in jsdefs.js by setting var consts = "var ";. If you get a native read in place I wouldn't be surprised if everything else just worked.
Shaper is also designed for being runnable in a browser. Check out <http://restrictmode.org/try> for one example showcasing the restricter plugin. In the current form this requires statically assembling together all the needed pieces into one file (build/all-restricter.js), but that could become more flexible in the future. It is expected to run on WebKit (v8 and JavaScriptCore powered) and Firefox, perhaps Opera too. If there's interest in IE we could get it running there too, with some modifications to Narcissus (getters). What this all means is that you could get a live "try jsdoc" running in the browser.
I wrote more about the underpinnings of how I implemented this in "JavaScript modules in shells, browsers, everywhere!" <http://blog.lassus.se/2011/04/javascript-modules-in-shells-browsers.html>.
/Olov
Michael
On May 14, 10:56 am, Olov Lassus <olov.las...@gmail.com> wrote:
> 14 maj 2011 kl. 08.03 skrev Michael:
>
> > You've created a great piece of
> > software that should make it possible, even enjoyable, for anyone to
> > rework JavaScript source code in whatever way they please.
>
> I need to save that quote somewhere. It is indeed the goal of Shaper.
>
> Right now plugins reside under the Shaper directory, in the future it will also be possible to run plugins that reside in your local JS project. This could be useful for one-off project specific Shaper-snippets. There will also be support for a project-level Shapefile (or .shaper, or something else) that specifies the plugin pipeline.
>
> > One critical requirement for JSDoc however is that it be runnable
> > under Rhino (as well as node, in version 3). I've been able to force
> > Narcissus to run under Rhino, with a Rhino-Require shim, plus a minor
> > tweak to their core code, but I wondered if you had any interest or
> > experience in this area?
>
> Sure. Here's an excerpt of the README (which need to be merged with jsshaper.org by the way):
>
> JSShaper is designed to run from the command line. It should be
> possible to use with the following JS shells:
> js: recent versions of Mozilla SpiderMonkey
> d8: Google V8 debug shell
> node: Embedded V8 with lots more
> It doesn't work with the JavaScriptCore jsc shell since it has no
> native read function.
> ---
>
> The prerequisites for getting a JavaScript shell working with Shaper is argument passing and native load and read functions. load for loading and executing another piece of JS code, read for reading a textfile to a string. For node, require and readFileSync are used instead.
>
> I didn't try Shaper with Rhino before, so I downloaded Rhino 1.7R3 and gave it a try. It seems to lack a native read function (or rather I found no), so you need to add that. It has argument passing and a native load though. Right now it bails out in Narcissus - Rhino doesn't seem to like Narcissus's technique of eval:ing constants. You can work around that temporarily in jsdefs.js by setting var consts = "var ";. If you get a native read in place I wouldn't be surprised if everything else just worked.
>
http://librelist.com/browser//nug/2011/4/30/porting-jsdoc-to-node/#2faefa266e38c3ddef8c91dde242df98
And, as you can see, you can make the fix without modifying the
Narcissus source files. Though I wish this would get fixed in either
Rhino or Narcissus properly!
Rhino has a global load() and can, via readFile(path [,
characterCoding]), read from files, if that's what you mean by a
"native read"? I built a shim version of require for Rhino but there
are others around, and it appears that the next release of Rhino will
have a native require built in.
Olov Lassus
> Rhino has a global load() and can, via readFile(path [,
> characterCoding]), read from files, if that's what you mean by a
> "native read"?
It is, thanks. In that case it's just the matter of selecting between readFileSync (node), readFile (Rhino) and read (the rest) at the end of run-shaper.js. I'll get to this later today. It could mean that we can add Rhino to the list of compatible shells.
/Olov
Olov Lassus
> I'll get to this later today. It could mean that we can add Rhino to the list of compatible shells.
Now confirmed. I just pushed out a require-refresh where everything is now relative the top-level Shaper directory. Use that version and apply the var-modif to Narcissus manually (I'll include that soon) and Shaper should run just fine in Rhino. And d8, js and node.
/Olov