Release - 0.5 beta
mic...@gmail.com
features. Fly mode template is now available with an example file
showing how to use it. A new plug-in to minimize source code is now
available, documented under the PlugIns page of the wiki.
http://code.google.com/p/jsdoc-2/
Regards,
Michael
chovy
All I got was a list of classes, and below that a list of
functions...there was no hierarchy at all conveyed, and constructions
were incorrectly generated as "new Class()" -- when it should be
something like "var myLibUtils = MyLib.myLibUtilClass";
Michael Mathews
I've written nine pages of documentation with step-by-step
instructions so it's not clear where in all that I've been
inconsistent or sparse. Can you be more specific? Are you looking at
the same documentation I am?
http://code.google.com/p/jsdoc-2/w/list
I'm not sure what you mean by "hierarchy." If you run JsDoc.js
against itself you should see that it correctly nests methods and
fields within their classes. If you mean that you don't see a diagram
showing the inheritance relationships from one class to another,
that's because such a feature hasn't been implemented. Yours would be
the first request for that and I'd have to consider adding it. Is
that what you mean?
If you're still unable to use JsDoc Toolkit after reading the
documentation feel free to post a link to your source code and I'm
sure I can tell you what's wrong.
Regards,
Michael
Anthony Ettinger
>
> Hello Chovy,
>
> I've written nine pages of documentation with step-by-step
> instructions so it's not clear where in all that I've been
> inconsistent or sparse. Can you be more specific? Are you looking at
> the same documentation I am?
> http://code.google.com/p/jsdoc-2/w/list
Yes, I have gone through these examples, and after re-reading again I
figured out my problem.
I needed to add "@method" instead of @function to my class methods.
I do have the methods and parameters associated with a @class now, but
is it possible to have the inheritance relationship?
ie - I believe jsdoc allowed
@class FooChild
@member Foo
...to designate the FooChild was a child class/field of Foo.
I am having diffuculting with jsdoctags that will depict the following
JSON hierarchy:
var myLib = {
util: {
Element: {
myMethod: function() {
my_property: 'some_value',
......
}
}
},
app: {
myAppMethod: function() {
}
}
}
Is there a way of associating "util" as a child of "myLib" or
"myMethod" as a child of "util".
The documentation has them in a flat list, ordered alphabetically.
>
> I'm not sure what you mean by "hierarchy." If you run JsDoc.js
> against itself you should see that it correctly nests methods and
> fields within their classes. If you mean that you don't see a diagram
> showing the inheritance relationships from one class to another,
> that's because such a feature hasn't been implemented. Yours would be
> the first request for that and I'd have to consider adding it. Is
> that what you mean?
see above JSON example...
I want to generate documentation similar to the YUI api documentation at:
http://developer.yahoo.com/yui/docs/YAHOO.util.Element.html
> If you're still unable to use JsDoc Toolkit after reading the
> documentation feel free to post a link to your source code and I'm
> sure I can tell you what's wrong.
also, I noticed @field tag does not seem to do anything except remove
the thing that it references from the documentation completly.
> Regards,
> Michael
>
> On 15 May 2007, at 20:41, chovy wrote:
>
> >
> > great, but i find the documentation rather sparse and inconsistent.
> >
> > All I got was a list of classes, and below that a list of
> > functions...there was no hierarchy at all conveyed, and constructions
> > were incorrectly generated as "new Class()" -- when it should be
> > something like "var myLibUtils = MyLib.myLibUtilClass";
> >
> >
> >
> > On May 9, 3:50 pm, micm...@gmail.com wrote:
> >> A new beta release 0.5 is now available with several bug fixes and
> >> new
> >> features. Fly mode template is now available with an example file
> >> showing how to use it. A new plug-in to minimize source code is now
> >> available, documented under the PlugIns page of the wiki.
> >>
> >> http://code.google.com/p/jsdoc-2/
> >>
> >> Regards,
> >> Michael
> >
> >
> > >
>
>
> >
>
--
Anthony Ettinger
Ph: 408-656-2473
http://chovy.dyndns.org/resume.html
http://utuxia.com/consulting
Michael Mathews
This is a _slightly_ tricky piece of code because you are nesting
object declarations all together in one go. Consider that your
example is identical to:
var myLib = {};
myLib.util = {};
myLib.util.Element = {};
myLib.util.Element.myMethod = function() {...}
and so on.
Now which of those many objects do you want to document? I count
seven named objects in total but I'll assume you want to document the
method, and the function, and in this case you must provide the full
runtime name of both of those. Same goes for the field.
You must also document the class to which that method belongs (which
I assume you want to be myLib.util.Element because you've named
Element with an upper-case). This "class" can't be instantiated with
"new" so it's considered "static" by JsDoc Toolkit.
var myLib = {
util: {
/**
* @static
* @class myLib.util.Element
*/
Element: {
/** @method myLib.util.Element.myMethod */
myMethod: function() {
/** @field myLib.util.Element.myMethod.my_property */
my_property: 'some_value',
......
}
}
},
app: {
/** @function myLib.app.myAppMethod */
myAppMethod: function() {
}
}
};
Hope that helps. If you have any other questions feel free to reply,
just remember that this is beta software and you are generously
volunteering to test software that is not yet fully complete.
Regards,
Michael
Anthony Ettinger
parameter is obviously an entire duplication of the code itself.
Is there a better way to build this library? I looked at your example,
which works, but also raises the question if I can lazy-load the
classes I need...my actual library is starting to grow wildly, and
many times I would rather just load the classes I need....perhaps this
is a bit off topic for this group however.
Michael Mathews
You've picked a worst-case example for JsDoc Toolki -- nested object
literal declarations are very hard to detect without a full-blown
JavaScript parser. The trouble is the curly-braces, or rather finding
the closing braces. Consider...
Foo.bar={
regexLiteral:/\\\}x{9}/,string:",\"\\"+"}}",//;/,}comment}
baz:{
}}
That's a simple example but you get the idea of the challenges to
trying to comprehend such nesting. I was, and still am to some
extent, on-the-fence about trying to implement a full-blown
JavaScript parser, or possibly using Rhino (or the Narcissus engine)
to do the work somehow, but there are problems with that...
Firstly a JavaScript parser is going to bloat the toolkit, in size
and slowness. It will require constant attention and tweaking to keep
it working correctly with all the edge cases: for example MicroSoft's
"conditional comments"
http://msdn2.microsoft.com/en-us/library/121hztk3(VS.71).aspx
And did you know that this was valid JavaScript: alert(1..toFixed
(2)) // 1.00
Easiest way around all that would be to try to use Rhino, but that
would kill off the entire fly-mode part of the toolkit (that's the
ability to use it within a web browser). And it gets worse: what if
you're using a bespoke framework that integrates heavily with the a
certain browser's DOM? Will Rhino know what to do with that?
On the other hand, if you consider that Perl has the POD system to
handle it's inline documentation and POD doesn't look at the code at
all, yet is very successful.
I think I've found a nice middle ground. In the easy cases (90% of
the time) JsDoc Toolkit can figure it out for you, but in the hard
cases (using a bespoke framework, or nesting object literals) you
have to be explicit.
You're reaction that this will be "an entire duplication of the code"
is a bit on an overstatement. It may look that way in this example
because your code doesn't actually do anything, but in real working
code the comments add about 30-50% to your line count, in my experience.
However, I include a stripper and a minimizer plugin which can be
used with the toolkit and those more than compensate for the extra
line weight.
Regards,
Michael
chovy
All I got was a list of classes, and below that a list of
functions...there was no hierarchy at all conveyed, and constructions
were incorrectly generated as "new Class()" -- when it should be
something like "var myLibUtils = MyLib.myLibUtilClass";
On May 9, 3:50 pm, micm...@gmail.com wrote:
Anthony Ettinger
I could not get my js lib to be parsed with the perl script in jsdoc
1.0...some reason it just returns "Nothing to do" everytime, runing
jsdoc.pl tests.js works though...oddly.
I believe I have some other issues related to how I define my library
layout that need to be addressed before spending too much time on
getting documentation to work.
> I think I've found a nice middle ground. In the easy cases (90% of
> the time) JsDoc Toolkit can figure it out for you, but in the hard
> cases (using a bespoke framework, or nesting object literals) you
> have to be explicit.
>
> You're reaction that this will be "an entire duplication of the code"
> is a bit on an overstatement. It may look that way in this example
> because your code doesn't actually do anything, but in real working
> code the comments add about 30-50% to your line count, in my experience.
Yes, that was an exaggeration on my part, just trying to convey my
point, but having to re-type the necessary info just above the real
function in the jsdoc would be rather cumbersome to maintain (at least
in my case).
> However, I include a stripper and a minimizer plugin which can be
> used with the toolkit and those more than compensate for the extra
> line weight.
Yes, I saw jslint, and some obfuscation tools as well, which will be
great once this thing goes to market.
Thanks for your responsiveness, I certainly don't expect, nor do I
want you to go a different direction to support a one-off case.
However, that being said, I have looked at a few libraries out there
for JSON-style notation that probably would have similar issue as
mine.
Anthony
mic...@gmail.com
the XP adage that the best documentation is the source code itself.
And JavaScript is a very difficult language to pin-down: it wants to
be Java and Scheme all at the same time. Coming up with a
documentation system for JS that works, let alone that pleases most
people, is a challenge.
However if you are to write documentation you will at some point need
to write: that is unavoidable. I understand that some people dream of
a tool that will scan their code and somehow just know what the intent
is and can describe it all coherently in human-readable form. I myself
wish for that on a regular basis, but, as I eluded to earlier, the
actual best format for that is to read the source code directly. But
this is a place for people who want to write documentation. The fact
that you have to explicitly specify the name of the code object you
are documenting in some cases isn't ideal but I'd say it's a
reasonable (best?) compromise, and I'm still eager to hear suggestions
for better alternatives.
Regards,
Michael
On May 16, 8:05 am, "Anthony Ettinger" <anth...@chovy.com> wrote:
Wenzel Peppmeyer
On May 16, 8:39 am, Michael Mathews <micm...@gmail.com> wrote:
> That's a simple example but you get the idea of the challenges to
> trying to comprehend such nesting. I was, and still am to some
> extent, on-the-fence about trying to implement a full-blown
> JavaScript parser, or possibly using Rhino (or the Narcissus engine)
> to do the work somehow, but there are problems with that...
I think you don't have to. Javascript itself is quite introspective.
You may want to take a look at a helper function (provided version is
simplified) I made to find out how foreign scripts pollute the global
object.
http://dexhome.homelinux.org/~dex/test/watchobj.xhtml
example: http://www.spiegel.de/js/http/0,5466,PB64-dmVyPTgmcmV2PTIwMDcwNTAzMDAwMSZzdHlsZT0mZW52X2xhbmd1YWdlPWRl,00.js
Paste a URL into the input field an hit return.
It does not traverse the added properties but that could be easily
done. If one would like to go a step further he could move the whole
documentation from comments into the javascript objects. I'm not sure
if that's a good idea because you may have a hard time to get them out
again if you don't got a Javascript runtime by hand. But imagine
firebugs console not only shows you details about objects (and thus
function objects) but also the documentation telling you what
parameters a function wants. That would be quite useful. :)
If you want to go that road wave here. I got some more (wild) ideas
about matter.
have fun
Wenzel
Michael Mathews
This is fun and very nifty indeed. It took me a few minutes to figure out how it worked, but I see it essentially injects a remote script into the loaded web page and then determines which new properties were added to the global window object as a result. Correct me if I'm wrong on that.
There are many approaches to trying to determine what structures a script contains, and early on in this project Gabriel Reid (the current JSDoc.pm maintainer) advocated vigorously for this same approach: evaluate and introspect. His reasoning then was that by running the code you could best determine what was in it. But I disagreed then and still do, because even though your solution seems to successfully implement that technique, I can still create examples where it falls down.
Okay, in the simplest cases it will work.
var fiddle = 1;
function faddle() {
}
posted here: http://www.michaelmathews.me.uk/t/js/introspect_1.js
I pop into your introspection script and it correctly identifies that the foreign script has added: faddle function, and fiddle number.
But because this technique requires the foreign script to actually evaluate in the introspecting web page, the hard case is when the foreign script depends on other scripts and/or there are objects being created conditionally. For example...
// note this script must be used in conjunction with the latest CoolLib.js script!
var browser = Lib.getBrowser();
var writer = null;
if (browser == "x") {
writer = Lib.x_writer ;
}
else {
writer = Lib.generic_writer;
}
writer.write("Hello world.");
posted here: http://www.michaelmathews.me.uk/t/js/introspect_2.js
Pop that into your introspection script and we get the much less useful result: writer undefined and browser undefined. Of course in the real world both of those would always be defined with objects, but how could your script possibly know that? I maintain it (and any similar script) can't.
There are even worse case scenarios too: imagine I am using a framework library (like prototype or similar) that handles all the details of creating Widgets for me. Like the above example, my own script assumes the enclosing web page will have already loaded the Framework.js library. So my script is simply:
Framework.Widgetmaker.make("A");
Framework.Widgetmaker.make("B");
Framework.Widgetmaker.make("C");
posted here: http://www.michaelmathews.me.uk/t/js/introspect_3.js
As the programmer, my intention is that there should be three global objects born by running this code, but it actually won't run at all out of its intended context, so if we try it in your introspection script it throws an error "Framework is not defined, introspect_3.js Line 1" and reports nothing at all.
This illustrates the fundamental problem with the whole evaluate-and-introspect approach, and to a lesser extent with the code-parsing approach too, it can't possibly capture the author's intent for code meant to be used in a specific context (with a particular framework, library or brand of browser).
Setting both of those approaches aside, look how easy life becomes when we allow the comment to be the primary mode of communication:
/**
* @static
* @class A
*/
Framework.Widgetmaker.make ("A");
/**
* @static
* @class B
*/
Framework.Widgetmaker.make("B");
/**
* @static
* @class C
*/
Framework.Widgetmaker.make("C");
I admit it's now more verbose, but this approach is guaranteed to work in every case, which is probably more important to more people than the extra lines in the source. And, because this technique doesn't require *any* code introspection at all, you can even put the comments in a separate file altogether and it will work exactly the same.
I consider code introspection to be helpful but only secondary to the real goal of accurate dependable documentation. I seriously would love to make JsDoc Toolkit even more helpful in it's ability to document code, so if you have any answers to these particular issues I'd welcome your thoughts.
Best Regards,
Michael
Michael Mathews
What if we provided a way for the file itself to tell us about dependencies? For example...
/**
* @requires http://example.com/CoolLibrary.js
*/
CoolLibrary.Classmaker.make("A");
Now we can load CoolLibrary.js before we evaluate the main script, and thus it should run, and introspection will reveal a new object was created named "A".
I like the idea of documenting dependencies anyway. Still not sure what to do about code that is meant to run based on the web browser but that may be a small enough problem that we can just punt.
Your thought?
--Michael
Michael Mathews
if (document.all) {
var screenWidth = document.body.offsetWidth;
} else if (document.layers) {
var screenWidth = window.innerWidth;
}
Am I right that the screenWidth global variable will thus be invisible to any introspection script? Punting may not be possible after all :(
Regards,
Michael
If I can follow-up... I just had a thought. There are 2 problems with evaluate-and-introspect: dependencies on code in separate files, and conditional object creation. I think we can solve one of those problems.
What if we provided a way for the file itself to tell us about dependencies? For example...
/**
* @requires http://example.com/CoolLibrary.js
*/
CoolLibrary.Classmaker.make ("A");
Wenzel Peppmeyer
On May 17, 1:21 pm, "Michael Mathews" <micm...@gmail.com> wrote:
> ... [ a lot mails] ...
I think I got a idea how we get introspective and parseable
( parseable like in RegExp ). Look at the following example:
foo = {
init: function(){},
sigClicked: function(){},
slotHide: function(){}
};
window.jsdoc = {};
window.jsdoc.foo = new JSDoc({type: "namespace", desc: "A namespace
to keep stuff." });
window.jsdoc.foo.jsdoc.init = new JSDoc({type: "method", desc: "A
contructor method." });
window.jsdoc.foo.jsdoc.sigClicked = new JSDoc({type: "signal", desc:
"Signal that is send when the object was clicked by a user." });
window.jsdoc.foo.jsdoc.slotHide = new JSDoc({type: "slot", desc: "A
slot that will hide the object per CSS rules." });
window.jsdoc.bar = new JSDoc({type: "function", desc: "Just a little
function that ain't do nothing."});
function bar(){};
What we do here is to add one (a singleton) object into the global
object. That object will contain documentations of all global
properties a lib/script is setting up. Firebug could lookup
window.jsdoc for "foo" and display the type, desc, etc. I bet your
Perl sharpened eyes already seen the nice patter new
JSDoc({ <stuff> }); Not only that it should be comparable easy to get
hold of that object literal, you can even eval it and use it right
away to feed templates with it. You can ban the whole bunch into a
separate file as well, if you like that better.
If you want to use it introspective the parts that are hidden behind
conditional stuff should be hidden anyway. So there is no problem
either. Dependencies are a big problem for Javascript and until we hit
2.0 wont go away. There are solutions like ajile.sf.net but they all
require you to have some sort of naming convention for .js and expect
stuff nice packaged in Java package like namespaces.
I'm serious about that! What means I'm coding right now to find out if
my idea works. Something worthwhile to spend a look at should be ready
tomorrow. I truly believe that hard things should be possible. :)
have fun
Wenzel
Wenzel Peppmeyer
On May 17, 4:52 pm, Wenzel Peppmeyer <Wenzel.Peppme...@googlemail.com>
wrote:
> I'm serious about that! What means I'm coding right now to find out if
> my idea works. Something worthwhile to spend a look at should be ready
> tomorrow. I truly believe that hard things should be possible. :)
Here you go:
http://wenzel.peppmeyer.googlepages.com/jsdoc-intro.html
There is an object defined and some docu written. There are a few
buttons to click at that show introspective behaviour. One property is
lookup up and found as not documented. It would not be hard to make it
clickable, show a form to type in the docu and then give the
definition Javascript code back to copy&past it into a file.
It's far from being useful but should show what i was thinking about.
Next step will be to add code to find the docu definitions in a script
without running the script itself. And then to execute the extractions
to build the DOM tree. That can be done even in comments. At least I
hope. :)
have fun
Wenzel