as some may have seen we have released a pure dojo based API docs viewer
http://dojodocs.uxebu.com/
some background info are available here
http://blog.uxebu.com/2009/03/12/pure-client-side-dojo-api-docs/
While working on it we made a couple of discoveries, which we would
like to share back and which hopefully serve as inspiration
or possible improvements regarding the API docs.
1) The mapping of classes/objects (whatever ou wanna call it) to filenames
is not coherent in all places. (It makes it hard to generate a
complete tree of all
classes and objects, since a file doesn't mean it is also a class and
vice versa,
but that was just the specific problem we had in the api docs project.)
The biggest flaw that imho is caused by it, is that the dojo.require()
always acts on the filesystem level and not on the class level. An example:
dojo.require("dojo.NodeList-fx") loads the "dojo/NodeList-fx.js" file
but has nothing
to do with the classname. The dojo.NodeList-fx won't exist afterwards, that is
something you will need to know how and why. Imho that makes it less intuitive
and hard for beginners, if they don't read the source code.
In e.g. dijit.form.Slider this problem has already been solved nicely
in really naming the files like the class, but there are still a
couple of private
classes in some files, like for example the "dijit.form._ComboBoxMenu" and even
the "dijit.form.ComboBoxMixin" inside the ComboBox.js.
Imho those should all go into separate files, also if this really
increases the number
of files (a build will leverage that), but it makes the loading and
mapping process
much more straightforward and allows for all kinds of automation because no
hidden knowledge is required to find those classes.
* Possible solution
Maybe something like this:
dojo.require("dojo.NodeList", {features:["fx", "html"]})
this loads the class "dojo.NodeList" with additional features, and
the call could also happen after dojo.NodeList had already been
loaded, it would just load the additional file with the not yet
loadded feature. That brings up another idea, you could also
load the localization this way
dojo.require("dojo.NodeList", {features:["fx", "html"],
locales:["en", "de"]})
And in order to not mistakenly "see" the files as classes, they
should also be stored into a detectable place, or at least the
rule should be set up, like
dojo/NodeList-fx.js
the "-fx" means this is the loadable feature "fx".
So this is actually already nicely solved, just needs to be written into
the coding style guide if commonly agreed upon.
This possible solution would even be backwards compatible.
2) Return values are spread across the source code and hard
to find. As in http://www.dojotoolkit.org/developer/StyleGuide defined
the return value types can be stated behind the return statement.
like so
if(arguments.length){
return "You passed argument(s)"; // String
}else{
return false; // Boolean
}
Imho it would be nicer to just list the return values above in the
docstring right after the function declaration, like so:
// returns: String
// If arguments are passed the string ... is returned.
// returns: Boolean
// If no arguments are passed false is returned.
This allows for any kind and number of return values too.
Thanks for the great work and high quality of dojo code,
it was really a pleasure creating the API docs, because there
was always a lot to learn and it was always pleasent to read
the code.
--
cu
Wolfram
http://uxebu.com - the AJAX experts
You need AJAX, RIA, JavaScript and all this modern stuff? We got it!
