Hi,

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!

Search Discussions

  • Tom Trenka at Mar 13, 2009 at 9:41 am
    Inline...
    On Fri, Mar 13, 2009 at 6:41 AM, Wolfram Kriesing wrote:

    Hi,

    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.

    So...we've been through this one before (though I'm pretty sure this was
    before you Uxebu guys got involved with the community); its always a cause
    for confusion, particularly for those that think dojo is basically a Java
    for JavaScript. But there's a difference between a *module* (like
    dojo.Nodelist) and a *resource* (like dojo.Nodelist-fx); without the
    resource concept, a lot of things that we do in the toolkit would not be
    possible (including the entire loader/bootstrap breakup across resources).

    I think the one thing that would be a bad idea is try to set up the codebase
    to "correct" this; it will cause greater confusion down the road, and it
    still wouldn't alleviate the problem because no matter how hard you try,
    there's still always going to be modules and resources.


    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"]})
    I would probably argue against this solution, mostly because of the pain
    you'll cause James and anyone else who works on the build system ;) Though
    it's an interesting idea.

    regards,
    trt

    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!
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: http://mail.dojotoolkit.org/pipermail/dojo-contributors/attachments/20090313/215afd3f/attachment.htm
  • Wolfram Kriesing at Mar 13, 2009 at 10:08 am

    2009/3/13 Tom Trenka <ttrenka at gmail.com>:
    Inline...
    On Fri, Mar 13, 2009 at 6:41 AM, Wolfram Kriesing
    wrote:
    Hi,

    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.
    So...we've been through this one before (though I'm pretty sure this was
    before you Uxebu guys got involved with the community); its always a cause
    for confusion, particularly for those that think dojo is basically a Java
    for JavaScript. ?But there's a difference between a *module* (like
    dojo.Nodelist) and a *resource* (like dojo.Nodelist-fx); without the
    resource concept, a lot of things that we do in the toolkit would not be
    possible (including the entire loader/bootstrap breakup across resources).

    I think the one thing that would be a bad idea is try to set up the codebase
    to "correct" this; it will cause greater confusion down the road, and it
    still wouldn't alleviate the problem because no matter how hard you try,
    there's still always going to be modules and resources.
    I completely agree that the dojo/_base stuff could be an exception, but
    even this could be "defined" by saying "the _base directory is an exception".
    But all the other stuff, like ComboBox* and NodeList-fx imho it would make
    sense.
    /me starts to like the dojo.require("", {}) synatx even more, just
    that it is a bit more magic ...

    This style
    dojo.require("dojo.NodeList", {features:["fx", "html"],
    locales:["en", "de"]})
    would map to the current style like this
    dojo.require("dojo.NodeList")
    dojo.require("dojo.NodeList-fx")
    dojo.require("dojo.NodeList-html")
    dojo.requireLocalization("dojo.NodeList", "en") // i dont know
    the exact syntax by heart ...
    dojo.requireLocalization("dojo.NodeList", "de") // i dont know
    the exact syntax by heart ...
  • Bill Keese at Mar 13, 2009 at 10:03 am

    Wolfram Kriesing wrote:
    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 dates back to when we first agreed on an inline doc format.

    Dojo intentionally diverges from javadoc/JSdoc format. This is partly
    the result of a religious debate about making our code comments as terse
    as possible, so as to:

    - avoid having more lines of documentation than lines of code.
    - avoid repeating stuff in the comments like variable names
  • Wolfram Kriesing at Mar 13, 2009 at 10:09 am

    On Fri, Mar 13, 2009 at 3:03 PM, Bill Keese wrote:
    Wolfram Kriesing wrote:
    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 dates back to when we first agreed on an inline doc format.

    Dojo intentionally diverges from javadoc/JSdoc format. ?This is partly
    the result of a religious debate about making our code comments as terse
    as possible, so as to:

    ? - avoid having more lines of documentation than lines of code.
    ? - avoid repeating stuff in the comments like variable names
    yeah sounds like it would become religious. So I dont write no pros+cons :-)
  • Wolfram Kriesing at Mar 15, 2009 at 8:51 am
    just as an additional info, the mapping we had to make by hand for
    the API viewer are listed here under "module2FilesMap"
    http://dojodocs.uxebu.com/uxebu/docs/setup.js
    and there are surely some missing!
    Imho most of them (except for the dojo._base stuff) could be resolved.
    The really relevant ones are in dijit and dojox.
    The dojo.require("", {features:[...]}) syntax would be especially handy for
    dojox.atom.io.model, as you can see a lot of mappings in this file.


    Another idea I just read about in the source code again linked above is:
    Maybe a __all__ property inside those namespaces would be a good idea.
    That is an idea borrowed from python, it could look like this
    for dijit.form
    dijit.form.__all__ = [
    "dijit.form.Button",
    "dijit.form.ComboBox",
    "dijit.form.CheckBox",
    .....
    ]

    to prevent bloat it could be stored in the __all__.js file in each directory.

    --
    cu

    Wolfram

    http://uxebu.com - the AJAX experts
    You need AJAX, RIA, JavaScript and all this modern stuff? We got it!



    On Fri, Mar 13, 2009 at 12:41 PM, Wolfram Kriesing
    wrote:
    Hi,

    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!
  • Shane O'Sullivan at Mar 15, 2009 at 9:26 am
    This __all__ idea actually used to exist, more or less, in 0.4.x.
    There was a _package.js file in most folders that included the base
    number of files required. It would be automatically included if you
    tried to dojo.require() that folder. It was removed as being
    considered too magic, and led to a big performance hit.

    However, this is a bit different - are you suggesting it would just be
    used for docs, not at runtime or build time?

    Shane

    2009/3/15 Wolfram Kriesing <wolfram.kriesing at gmail.com>:
    just as an additional info, the mapping we had to make by hand for
    the API viewer are listed here under "module2FilesMap"
    ? ? http://dojodocs.uxebu.com/uxebu/docs/setup.js
    and there are surely some missing!
    Imho most of them (except for the dojo._base stuff) could be resolved.
    The really relevant ones are in dijit and dojox.
    The dojo.require("", {features:[...]}) syntax would be especially handy for
    dojox.atom.io.model, as you can see a lot of mappings in this file.


    Another idea I just read about in the source code again linked above is:
    ? ? Maybe a __all__ property inside those namespaces would be a good idea.
    That is an idea borrowed from python, it could look like this
    for dijit.form
    dijit.form.__all__ = [
    ? "dijit.form.Button",
    ? "dijit.form.ComboBox",
    ? "dijit.form.CheckBox",
    ? .....
    ]

    to prevent bloat it could be stored in the __all__.js file in each directory.

    --
    cu

    Wolfram

    http://uxebu.com - the AJAX experts
    You need AJAX, RIA, JavaScript and all this modern stuff? We got it!



    On Fri, Mar 13, 2009 at 12:41 PM, Wolfram Kriesing
    wrote:
    Hi,

    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!
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Wolfram Kriesing at Mar 15, 2009 at 9:32 am

    On Sun, Mar 15, 2009 at 2:26 PM, Shane O'Sullivan wrote:
    This __all__ idea actually used to exist, more or less, in 0.4.x.
    There was a _package.js file in most folders that included the base
    number of files required. ?It would be automatically included if you
    tried to dojo.require() that folder. ?It was removed as being
    considered too magic, and led to a big performance hit.

    However, this is a bit different - are you suggesting it would just be
    used for docs, not at runtime or build time?
    Well using it for the docs would be the cause that made me come
    up with it, but others could use it too, yes.
    dojo.require() shouldnt need to load it, so no performance issues
    there, just more work initially :-)
    And the __all__.js file would actually really just contain a list
    of the names, not do any requires or whatever. It's purely
    informational and adds the property "__all__" to the object.

    Wolfram
    Shane

    2009/3/15 Wolfram Kriesing <wolfram.kriesing at gmail.com>:
    just as an additional info, the mapping we had to make by hand for
    the API viewer are listed here under "module2FilesMap"
    ? ? http://dojodocs.uxebu.com/uxebu/docs/setup.js
    and there are surely some missing!
    Imho most of them (except for the dojo._base stuff) could be resolved.
    The really relevant ones are in dijit and dojox.
    The dojo.require("", {features:[...]}) syntax would be especially handy for
    dojox.atom.io.model, as you can see a lot of mappings in this file.


    Another idea I just read about in the source code again linked above is:
    ? ? Maybe a __all__ property inside those namespaces would be a good idea.
    That is an idea borrowed from python, it could look like this
    for dijit.form
    dijit.form.__all__ = [
    ? "dijit.form.Button",
    ? "dijit.form.ComboBox",
    ? "dijit.form.CheckBox",
    ? .....
    ]

    to prevent bloat it could be stored in the __all__.js file in each directory.

    --
    cu

    Wolfram

    http://uxebu.com - the AJAX experts
    You need AJAX, RIA, JavaScript and all this modern stuff? We got it!



    On Fri, Mar 13, 2009 at 12:41 PM, Wolfram Kriesing
    wrote:
    Hi,

    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!
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Bill Keese at Mar 15, 2009 at 10:05 am

    Wolfram Kriesing wrote:
    just as an additional info, the mapping we had to make by hand for
    the API viewer are listed here under "module2FilesMap"
    http://dojodocs.uxebu.com/uxebu/docs/setup.js
    FWIW most of the dijit classes have been split off to individual files
    although some can't be split until 2.0, for back-compat reasons. (ex:
    dijit.form.DropDownButton depends on dijit.form.Button, but for
    back-compat reasons dojo.require("dijit.form.Button") needs to pull in
    DropDownButton... that creates a circular dependency)
  • Alex Russell at Mar 15, 2009 at 2:08 pm

    On Mar 15, 2009, at 5:51 AM, Wolfram Kriesing wrote:

    just as an additional info, the mapping we had to make by hand for
    the API viewer are listed here under "module2FilesMap"
    http://dojodocs.uxebu.com/uxebu/docs/setup.js
    and there are surely some missing!
    Imho most of them (except for the dojo._base stuff) could be resolved.
    The really relevant ones are in dijit and dojox.
    The dojo.require("", {features:[...]}) syntax would be especially
    handy for
    dojox.atom.io.model, as you can see a lot of mappings in this file.
    This is going to make it hard on other tools that try to process
    dojo.require() statements (like the build tools). The "NodeList-fx"
    syntax is designed to help you understand what's going on inside the
    file. Where we haven't been putting code in it's namespace, I consider
    that a bug to be fixed (see: dijit.form.Button).
    Another idea I just read about in the source code again linked above
    is:
    Maybe a __all__ property inside those namespaces would be a good
    idea.
    That is an idea borrowed from python, it could look like this
    for dijit.form
    dijit.form.__all__ = [
    "dijit.form.Button",
    "dijit.form.ComboBox",
    "dijit.form.CheckBox",
    .....
    ]

    to prevent bloat it could be stored in the __all__.js file in each
    directory.

    Something like this was in a previous version of the package system
    (it used __package__.js files). It was a mistake and has subsequently
    been dropped.

    I realize that client-side parsing tools have a problem that server-
    side generators don't in this regard, but it's not clear what other
    value an __all__.js file will have beyond making things easier for
    this particular tool. Would there be other clients for this data?

    Regards

    - --
    Alex Russell
    slightlyoff at google.com
    alex at dojotoolkit.org BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723
  • Wolfram Kriesing at Mar 16, 2009 at 5:53 am

    Another idea I just read about in the source code again linked above
    is:
    ? ? Maybe a __all__ property inside those namespaces would be a good
    idea.
    That is an idea borrowed from python, it could look like this
    for dijit.form
    dijit.form.__all__ = [
    ? "dijit.form.Button",
    ? "dijit.form.ComboBox",
    ? "dijit.form.CheckBox",
    ? .....
    ]

    to prevent bloat it could be stored in the __all__.js file in each
    directory.

    Something like this was in a previous version of the package system
    (it used __package__.js files). It was a mistake and has subsequently
    been dropped.

    I realize that client-side parsing tools have a problem that server-
    side generators don't in this regard, but it's not clear what other
    value an __all__.js file will have beyond making things easier for
    this particular tool. Would there be other clients for this data?
    I don't know right now. Right now I can't think of any.
    Additionally it increases transparency and completeness, since you
    will know exactly what
    is meant to be inside the "dojo" namespace for example, if you only
    have to look it up in the dojo/__all__.js . Because currently there
    are also things like OpenAjax.js, Jaxer.js and alikes in there, which
    also a server-side parser would have to dismiss using a hand-written
    list I guess (or be overly smart).
    And it's true, it would just add up on the workload of the devs to
    also maintain yet another file, it shouldn't be included in the build
    or by dojo.require(), normally.

    Wolfram
  • James Burke at Mar 15, 2009 at 1:52 pm

    On Fri, Mar 13, 2009 at 4:41 AM, Wolfram Kriesing wrote:
    Hi,

    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.
    The dojo.NodeList-fx naming was chosen because it does not map to a
    normal Javascript object -- you cannot use dashes in object names,
    like dojo.NodeList-fx.someFunction(). This was chosen to represent
    modules that extend an existing function/object.
    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.
    As Bill mentioned, I think the overall goal for dijit is to get more
    of a one-to-one mapping.
    * 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.
    It is not clear to me this solves any of the file mapping issues for
    documentation. We still would have the same file mappings as before,
    and the documentation builder still has to know the same rules as
    today?

    Specifying locales makes the code less portable too -- If I deliver my
    custom module that uses the style above, if someone else wants to use
    my custom module but for "fr", they would be stuck. You could say that
    rule only applies for top-level require calls in a page, but it seems
    much less useful, and we are giving degrees of freedom that will
    likely be misused.

    It is unfortunate you need to keep a manual mapping in your API tool.
    I was under the impression our doc parser had the ability to tell us
    what functions were in what file, and I thought your API viewer was
    consuming some form of output from that parser? Or do you have your
    own custom doc parser? I would prefer to get the solution for the docs
    via a somebody's doc parser solution.

    I think the general rules for modules are:
    - Use a separate file for each distinct object.
    - For things that extend other objects, like dojo.NodeList-fx, use the
    dash notation to indicate it is not really a stand-alone
    module/object, but an extension module.
    - Resource names that have _ in their name may do tricky things,
    aggregate functionality across files, like dojo._base, dijit._base and
    all the dojox modules that have a top level name, like dojox.gfx, may
    load things from a module-specific _base.js file, like
    dojox.gfx._base.

    So really any mapping of functionality to files will have to
    understand javascript to know what functionality is in what module.

    James
  • Wolfram Kriesing at Mar 15, 2009 at 6:05 pm

    * 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.
    It is not clear to me this solves any of the file mapping issues for
    documentation. We still would have the same file mappings as before,
    and the documentation builder still has to know the same rules as
    today?
    Right, the filenames stay the same.
    But since dojo.require() depends on knowing that a feature
    is saved in the file with the ending "-fx" it is just enforcing the
    rule. And if this rule will be common throughout the toolkit
    it will be just one rule that needs to be known.
    And imho a
    dojo.require("dojo.NodeList", {features:["fx", "html"]})
    makes more sense than the
    dojo.require("dojo.NodeList")
    dojo.require("dojo.NodeList-fx")
    since it basically is more compact and the logic can be
    "stored away", which could also be seen as magic of course :-).

    I guess the conclusion is that the filename rule "NodeList-whatever.js"
    just needs to be enforced. Extending the dojo.require() is just
    a logical next step and not necessary, but I like it :-).
    It is unfortunate you need to keep a manual mapping in your API tool.
    I was under the impression our doc parser had the ability to tell us
    what functions were in what file, and I thought your API viewer was
    consuming some form of output from that parser? Or do you have your
    own custom doc parser? I would prefer to get the solution for the docs
    via a somebody's doc parser solution.
    Our parser actually spun off of a completely browser based solution,
    so we actually hadn't even thought of using any generated data.
    And somehow we liked the completely client-based approach :-).
    I think the general rules for modules are:
    - Use a separate file for each distinct object.
    - For things that extend other objects, like dojo.NodeList-fx, use the
    dash notation to indicate it is not really a stand-alone
    module/object, but an extension module.
    +1

    Wolfram
  • James Burke at Mar 16, 2009 at 12:07 am

    On Sun, Mar 15, 2009 at 3:05 PM, Wolfram Kriesing wrote:
    Right, the filenames stay the same.
    But since dojo.require() depends on knowing that a feature
    is saved in the file with the ending "-fx" it is just enforcing the
    rule. And if this rule will be common throughout the toolkit
    it will be just one rule that needs to be known.
    And imho a
    ? ?dojo.require("dojo.NodeList", {features:["fx", "html"]})
    makes more sense than the
    ? ?dojo.require("dojo.NodeList")
    ? ?dojo.require("dojo.NodeList-fx")
    since it basically is more compact and the logic can be
    "stored away", which could also be seen as magic of course :-).

    I guess the conclusion is that the filename rule "NodeList-whatever.js"
    just needs to be enforced. Extending the dojo.require() is just
    a logical next step and not necessary, but I like it :-).
    Yeah i think the features thing still obscures it for the user: how
    are they to know what that loads and where does it load from? What if
    the actual modules lives in dojox or some other space, not in dojo?

    Even though the explicit require may be more verbose, it is uniform,
    consistent, and the user only has to learn one way of loading in
    modules, and a simple algorithm to generating resource names to file
    paths.

    Besides, the place where you might want the extensions, like "fx" and
    "html" may not be the place where the dojo.require("dojo.NodeList")
    occurred. In fact, for NodeList, it never is, since NodeList is
    delivered in base. So it is unlikely this specific example would ever
    be used in practice. I and would bet most if not all the extension
    modules actually extend something that is in some sort of _base
    deliverable.
    It is unfortunate you need to keep a manual mapping in your API tool.
    I was under the impression our doc parser had the ability to tell us
    what functions were in what file, and I thought your API viewer was
    consuming some form of output from that parser? Or do you have your
    own custom doc parser? I would prefer to get the solution for the docs
    via a somebody's doc parser solution.
    Our parser actually spun off of a completely browser based solution,
    so we actually hadn't even thought of using any generated data.
    And somehow we liked the completely client-based approach :-).
    Sounds neat. I liked the idea of running the doc parser code as
    JavaScript operating on JavaScript. I assumed this would run in
    something like rhino, but neat if you were able to work it out just
    parsing files in the browser. Although still seems like you have a
    transform step: parse the JS files, turn that into HTML pages, or at
    least a JS structure you can load? The regular doc parser seems like
    it also emits an intermediary structure, but I am not sure how usable
    it is for your tool.

    In any case, seems like the doc parser needs to be smart enough to
    parse (or even run?) javascript to generate the docs -- over time it
    may be hard maintaining the manual mapping list. It is doable, but
    takes long term commitment. But then so does a doc parser. :)

    James

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupdojo-contributors @
categoriesdojo
postedMar 13, '09 at 7:41a
activeMar 16, '09 at 5:53a
posts14
users6
websitedojotoolkit.org

People

Translate

site design / logo © 2022 Grokbase