Javadoc-style tool for JavaScript at SourceForge
Gabriel Reid
http://sourceforge.net/projects/jsdoc/ under the 'jsdoc' package. It
requires Perl (as well as the HTML::Template module), which are all
freely available. The idea of the parser is to handle
(prototype-based) Object-Oriented source files almost exactly as
Javadoc(it uses the javadoc doclet as its template), including
creating an index, showing (prototype-based) inheritance, etc. Keep in
mind that this is beta-version software, so there may still be some
bugs (if you find any or many, please contact me at
gab_...@users.sourceforge.net). Support for general public functions
(not associated with a 'class') and other features will be coming
soon.
Gabriel
Douglas Crockford
I made a jsdoc package of my own a couple of years ago, written in JavaScript.
JavaScript is considerably more dynamic than Java, and so I found that the
documentation language required more explicit structure than JavaDoc does.
For example, a function can be a class (or constructor), or a static method, or
an instance method, or just a function. It is not possible to tell by simple
analysis, and documentation that merely reports that functions are functions is
worthless because it is obscuring structure rather than revealing it.
This gets more complicated when working in a dynamic style with constructs like
MyClass.inherits(YourClass);
MyClass.method('name', function (...) {...});
I didn't see documentation at SourceForge. How do you cope with structure?
Gabriel Reid
JavaScript.
> JavaScript is considerably more dynamic than Java, and so I found that the
> documentation language required more explicit structure than JavaDoc does.
>
> For example, a function can be a class (or constructor), or a static
method, or
> an instance method, or just a function. It is not possible to tell by
simple
> analysis, and documentation that merely reports that functions are
functions is
> worthless because it is obscuring structure rather than revealing it.
>
> This gets more complicated when working in a dynamic style with constructs
like
>
> MyClass.inherits(YourClass);
> MyClass.method('name', function (...) {...});
>
> I didn't see documentation at SourceForge. How do you cope with structure?
>
> http://www.crockford.com/javascript/inheritance.html
>
At the moment, the structure that is handled by the parser is assignment of
functions (either named or anonymous) or (non-function) properties to class
(function) prototypes, and inheritance is recognized by assigning an
instance of a class to a subclass's prototype. Class-level (static) methods
and properties are also recognized. For example:
function Shape(){} // Class
Shape.prototype.getName = Shape_GetName; // Assignment of a named function
as an instance method
Shape.prototoype.getSize = function(){}// Assignment of a nameless function
as an instance method
function Shape_GetName(){return "";} // Definition of method to be used as
an instance method
function Circle(){}// Class
Circle.prototype = new Shape(); // Circle inherits from Shape
Circle.PI = 3.14; // Class property
More dynamic constructs, such as the type you listed, would not yet be
recognized. However, my goal in posting information about this project is to
get feedback and possibly further help on the project to make it handle the
cases which you pointed out.
The package comes with an example js file that shows a small class hierarchy
so that the general abilities of the parser can be seen. I encourage anyone
who is interested to give it a try, and let me know if you find problems or
limitations to the application. I'm also interested in hearing from anyone
else who is interested in helping make improvements to the app.
Gabriel
Richard Cornford
<snip>
>> MyClass.inherits(YourClass);
>> MyClass.method('name', function (...) {...});
>>
>> I didn't see documentation at SourceForge. How do you cope with
>>structure?
>At the moment, the structure that is handled by the parser is
assignment
>of functions (either named or anonymous) or (non-function) properties
to
>class (function) prototypes, and inheritance is recognized by assigning
>an instance of a class to a subclass's prototype. Class-level (static)
>methods and properties are also recognized. For example:
Douglas Crockford's 'inherits' and 'method' (and others) functions are
added to the Function.prototype and serve to automate various aspects of
inheritance. In the process they modify the behaviour of functions.
If something like - Circle.prototype = new Shape(); - happens more than
twice, it becomes more efficient to move the code that sets up the
subclass into a separate function (and a method of the Function class
seems like a good location for those automating functions).
Unfortunately the names, code and location of that type of Class
creation automation function would be entirely at the whim of the
author. Possibly to a point where the only way of working out what
structure of Functions the code would produce would be to feed the code
into a (custom) JavaScript interpreter and examine the structure of the
Functions that it created.
>function Shape(){} // Class
>Shape.prototype.getName = Shape_GetName; //Assignment of a named
function
>as an instance method
>Shape.prototoype.getSize = function(){}//Assignment of a nameless
function
>as an instance method
>function Shape_GetName(){return "";} //Definition of method to be used
as
>an instance method
>function Circle(){}// Class
>Circle.prototype = new Shape(); // Circle inherits from Shape
>Circle.PI = 3.14; // Class property
>
>More dynamic constructs, such as the type you listed, would not yet be
>recognized. However, my goal in posting information about this project
>is to get feedback and possibly further help on the project to make it
>handle the cases which you pointed out.
<snip>
Generally I like the idea of a system that could automate the
presentation of documentation for JavaScript but I would not like that
system to limit the code that could be authored to a mundane and ridged
subset of possibilities (and especially at the cost of efficiency or an
avoidable increase in the size of the source code for client side work).
I would definitely hope that you could include the category of public
instance methods that Douglas categorises as 'privileged'. Constructor
inner functions assigned to public instance members:-
function MyObject(){
var name;
. . .
this.setName = function(nm){
name = nm;
};
this.getName = function(){
return name;
};
. . .
}
MyObject.prototype.formatName = function(){
return '<< '+this.getName()+' >>';
};
- As omitting public methods created in that way would render
documentation point-less (and baring that construct because it is not
practical to document it automatically would be an unacceptable
restriction to place on JavaScript).
Are you attempting to cope with inner classes (with potentially infinite
nesting)?
function MyObject(){
var name;
. . .
function InnerObj(){
. . .
this.getInstName = function(){
return name;
};
};
this.getInterfaceX = function(){
return new InnerObj();
};
}
- With the possibility of anonymous inner classes?:-
function MyObject(){
var name;
. . .
this.getInterfaceX = function(){
return new (function(){
. . .
this.getInstName = function(){
return name;
};
})();
};
}
And how about structures that give public class (static) methods access
to private class (static) members?
var MyObject = function(){
var privateStaticVar = 2.34;
function constructor(){
var name;
. . .
this.setName = function(nm){
name = nm;
};
this.getName = function(){
return name;
};
. . .
};
//define public static member.
constructor.doCalculation = function(x){
return (x*privateStaticVar);
};
return constructor;
}(); //simultaneously define and call (one-off)!
MyObject.prototype.formatName = function(){
return '<< '+this.getName()+' >>';
};
OK, they are not all structures that are in common use, but they are all
perfectly valid and exploitable aspects of OO JavaScript programming. I
would not like the requirements of an automated documentation system to
prevent me from realising (either conceptually or in code) the
possibilities that JavaScript has to offer.
(Unless of course those restrictions could be backed up with strong
arguments for 'best practice' or from OO programming theory. 1-2 levels
of nested inner classes = OK - infinite nesting = ludicrous and
unmanageable. Anonymous inner classes = incomprehensible source code.)
Richard.
Douglas Crockford
> creation automation function would be entirely at the whim of the
> author. Possibly to a point where the only way of working out what
> structure of Functions the code would produce would be to feed the code
> into a (custom) JavaScript interpreter and examine the structure of the
> Functions that it created.
The approach I took in my jsdoc was to add doctags specifically to describe
program structure.
@function
@class
@method
@class-method
@object
@var
@member
and so on.
Richard Cornford
<snip>
>The approach I took in my jsdoc was to add doctags specifically
>to describe program structure.
>
> @function
> @class
> @method
> @class-method
> @object
> @var
> @member
>
>and so on.
So, move the responsibility for describing the structure from the
software to . . . errr . . . the one person who should be expected
to understand the structure. OK, that seems fair.
Richard.
Gabriel Reid
"Richard Cornford" <Ric...@litotes.demon.co.uk> wrote in message
news:b8m4hq$da1$1$8300...@news.demon.co.uk...
<snip>
> Generally I like the idea of a system that could automate the
> presentation of documentation for JavaScript but I would not like that
> system to limit the code that could be authored to a mundane and ridged
> subset of possibilities (and especially at the cost of efficiency or an
> avoidable increase in the size of the source code for client side work).
>
> I would definitely hope that you could include the category of public
> instance methods that Douglas categorises as 'privileged'. Constructor
> inner functions assigned to public instance members:-
>
> function MyObject(){
> var name;
> . . .
> this.setName = function(nm){
> name = nm;
> };
> this.getName = function(){
> return name;
> };
> . . .
> }
> MyObject.prototype.formatName = function(){
> return '<< '+this.getName()+' >>';
> };
>
> - As omitting public methods created in that way would render
> documentation point-less (and baring that construct because it is not
> practical to document it automatically would be an unacceptable
> restriction to place on JavaScript).
Currently 'privileged' members are not handled. My rationale for this is the
my limits of time, and the fact that the JavaScript code I write always
assigns instance methods to the prototype, if only for efficiency. I realize
that this does not cover a large amount of JavaScript code, and for that
reason I will say that adding handling for this type of construct will be
one of my highest-priority tasks for further work on this project. Although
the parser will not pick up these constructs, it will also not be broken by
them, it will just ignore them for now.
> Are you attempting to cope with inner classes (with potentially infinite
> nesting)?
>
> - With the possibility of anonymous inner classes?:-
>
> And how about structures that give public class (static) methods access
> to private class (static) members?
>
> OK, they are not all structures that are in common use, but they are all
> perfectly valid and exploitable aspects of OO JavaScript programming. I
> would not like the requirements of an automated documentation system to
> prevent me from realising (either conceptually or in code) the
> possibilities that JavaScript has to offer.
>
None of the above constructs are handled either, and I would say that they
will not be considered high-priority for now, although they may certainly be
added at a later time. As I say, this tool was originally written for my own
use, and thus was created with my own needs in mind. However, in releasing
it to the outside world, I'm hoping to get constructive criticism like this
(as well as assistance) in making it into a tool that can be useful to a
wider audience.
If you decide to try it out, please let me know of any other strong or weak
points or anything else that you find with it.
Regards,
Gabriel Reid