Quantcast

Documentation

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Documentation

zet4080
Hi!

I know this subject was discussed a hundred times before (I scanned the
archives), but I want to share my thoughts ....

I'm working for a software company in Germany and I'm looking for a
JavaScript-Library to use in the project I'm working on at the moment.

I found dojo and I personally think it is very good work, I really like it,
especially dojo.io.bind and the "require" mechanism.

Now I tried to use the widgets .... I think I must cease it and perhaps even
cease the use of the toolkit because of the lack of documentation.

The point is: of course I could make it with "trial and error", perhaps
there is enough information in the interests group archives, and if I want
to use dojo for private purpose only I'm soure I would even enjoy it doing
it that way .... but as I want to use it on work, I just don't have time for
things like that!

I can't try, post in the forum, scan the archives, try again, post again,
wait again .... it's impossible to do this in a professional environment!

I really think the success of dojo in the near future will depend to some
(great) extent on the quality of the documentation .... what are all the
great features worth if no one can find them?

Again, I really, really like dojo and I will try to use it for one or two
more days, but I fear that I can't make progress fast enough in my boss's
opinion ....

Regards,
Jochen Zimmermann

_______________________________________________
Dojo FAQ: http://dojo.jot.com/FAQ
[hidden email]
http://dojotoolkit.org/mailman/listinfo/dojo-interest
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Documentation

Eric Segal
Yes - I am in exactly the same situation. Dojo is fantastic, but it is not
really Useful (with a capital U) until someone with no dojo background can
pick up the library, read a couple of pages, and then get it working. I
appreciate all the hard work that you all are doing and I am looking forward
to that day!

Until then, it would be useful to me if I could just hire someone for an
hour or two to help me get the library installed and the widgets working.
Any takers?

Eric Segal
([hidden email])

----- Original Message -----
From: "Jochen Zimmermann" <[hidden email]>
To: <[hidden email]>
Sent: Tuesday, March 07, 2006 5:28 AM
Subject: ***SPAM -- LOW *** [Dojo-interest] Documentation


> Hi!
>
> I know this subject was discussed a hundred times before (I scanned the
> archives), but I want to share my thoughts ....
>
> I'm working for a software company in Germany and I'm looking for a
> JavaScript-Library to use in the project I'm working on at the moment.
>
> I found dojo and I personally think it is very good work, I really like
> it,
> especially dojo.io.bind and the "require" mechanism.
>
> Now I tried to use the widgets .... I think I must cease it and perhaps
> even
> cease the use of the toolkit because of the lack of documentation.
>
> The point is: of course I could make it with "trial and error", perhaps
> there is enough information in the interests group archives, and if I want
> to use dojo for private purpose only I'm soure I would even enjoy it doing
> it that way .... but as I want to use it on work, I just don't have time
> for
> things like that!
>
> I can't try, post in the forum, scan the archives, try again, post again,
> wait again .... it's impossible to do this in a professional environment!
>
> I really think the success of dojo in the near future will depend to some
> (great) extent on the quality of the documentation .... what are all the
> great features worth if no one can find them?
>
> Again, I really, really like dojo and I will try to use it for one or two
> more days, but I fear that I can't make progress fast enough in my boss's
> opinion ....
>
> Regards,
> Jochen Zimmermann
>
> _______________________________________________
> Dojo FAQ: http://dojo.jot.com/FAQ
> [hidden email]
> http://dojotoolkit.org/mailman/listinfo/dojo-interest 
_______________________________________________
Dojo FAQ: http://dojo.jot.com/FAQ
[hidden email]
http://dojotoolkit.org/mailman/listinfo/dojo-interest
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation

Yi Tan
Hi

I'm very new to dojo, and have the same problem since we are considering using dojo to replace our currently js framework.

I have been using a versatile document generator called Doxygen (<a href="http://www.stack.nl/%7Edimitri/doxygen/" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)"> http://www.stack.nl/~dimitri/doxygen/) for other Java and ActionScript developments for a while. It's an excellent tool.

Since dojo developers are using JDoc comments style in the JS code. I just tried to use Doxygen on dojo, and it does recognise the code in some extent. But because OO programing in JavaScript is simulated by coding on prototype, Doxygen can't find out the relationship between source files.

At least, I now have a document of dojo with files list, members list and colourised code. Which make my life much easir.


If you want to have a copy of the configuration file / generated document, please drop me a line at: [hidden email]

And I'm not a expert of doxygen, I guess it must be able to product a much better documentation. If you knows, please tell me.

Regards,

Yi


On 3/7/06, Eric Segal <[hidden email]> wrote:
Yes - I am in exactly the same situation. Dojo is fantastic, but it is not
really Useful (with a capital U) until someone with no dojo background can
pick up the library, read a couple of pages, and then get it working. I
appreciate all the hard work that you all are doing and I am looking forward
to that day!

Until then, it would be useful to me if I could just hire someone for an
hour or two to help me get the library installed and the widgets working.
Any takers?

Eric Segal
([hidden email])

----- Original Message -----
From: "Jochen Zimmermann" <[hidden email]>
To: <[hidden email]>
Sent: Tuesday, March 07, 2006 5:28 AM
Subject: ***SPAM -- LOW *** [Dojo-interest] Documentation


> Hi!
>
> I know this subject was discussed a hundred times before (I scanned the
> archives), but I want to share my thoughts ....
>
> I'm working for a software company in Germany and I'm looking for a
> JavaScript-Library to use in the project I'm working on at the moment.
>
> I found dojo and I personally think it is very good work, I really like
> it,
> especially dojo.io.bind and the "require" mechanism.
>
> Now I tried to use the widgets .... I think I must cease it and perhaps
> even
> cease the use of the toolkit because of the lack of documentation.
>
> The point is: of course I could make it with "trial and error", perhaps
> there is enough information in the interests group archives, and if I want
> to use dojo for private purpose only I'm soure I would even enjoy it doing
> it that way .... but as I want to use it on work, I just don't have time
> for
> things like that!
>
> I can't try, post in the forum, scan the archives, try again, post again,
> wait again .... it's impossible to do this in a professional environment!
>
> I really think the success of dojo in the near future will depend to some

> (great) extent on the quality of the documentation .... what are all the
> great features worth if no one can find them?
>
> Again, I really, really like dojo and I will try to use it for one or two
> more days, but I fear that I can't make progress fast enough in my boss's
> opinion ....
>
> Regards,
> Jochen Zimmermann
>
> _______________________________________________
> Dojo FAQ: http://dojo.jot.com/FAQ
> [hidden email]
> http://dojotoolkit.org/mailman/listinfo/dojo-interest
_______________________________________________
Dojo FAQ: http://dojo.jot.com/FAQ
[hidden email]
http://dojotoolkit.org/mailman/listinfo/dojo-interest


_______________________________________________
Dojo FAQ: http://dojo.jot.com/FAQ
[hidden email]
http://dojotoolkit.org/mailman/listinfo/dojo-interest
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation

Alex Russell
We've looked at Doxygen, JSDoc, and any number of other JS documentation
alternatives. They all suck for a language that's as dynamic as
JavaScript. We have a new doc tool in the works that should fix most of
the issues of JSDoc and Doxygen. The new system also doesn't require
the grotty JavaDoc syntax for writing our documentation.

I'll post back here when we have a demo up.

Regards

On Wednesday 08 March 2006 7:44 am, Yi Tan wrote:

> Hi
>
> I'm very new to dojo, and have the same problem since we are
> considering using dojo to replace our currently js framework.
>
> I have been using a versatile document generator called Doxygen
> (http://www.stack.nl/~dimitri/doxygen/<http://www.stack.nl/%7Edimitri
>/doxygen/>) for other Java and ActionScript developments for a while.
> It's an excellent tool.
>
> Since dojo developers are using JDoc comments style in the JS code. I
> just tried to use Doxygen on dojo, and it does recognise the code in
> some extent. But because OO programing in JavaScript is simulated by
> coding on prototype, Doxygen can't find out the relationship between
> source files.
>
> At least, I now have a document of dojo with files list, members list
> and colourised code. Which make my life much easir.
>
>
> If you want to have a copy of the configuration file / generated
> document, please drop me a line at: [hidden email]
>
> And I'm not a expert of doxygen, I guess it must be able to product a
> much better documentation. If you knows, please tell me.
>
> Regards,
>
> Yi
>
> On 3/7/06, Eric Segal <[hidden email]> wrote:
> > Yes - I am in exactly the same situation. Dojo is fantastic, but it
> > is not really Useful (with a capital U) until someone with no dojo
> > background can pick up the library, read a couple of pages, and
> > then get it working. I appreciate all the hard work that you all
> > are doing and I am looking forward
> > to that day!
> >
> > Until then, it would be useful to me if I could just hire someone
> > for an hour or two to help me get the library installed and the
> > widgets working. Any takers?
> >
> > Eric Segal
> > ([hidden email])
> >
> > ----- Original Message -----
> > From: "Jochen Zimmermann" <[hidden email]>
> > To: <[hidden email]>
> > Sent: Tuesday, March 07, 2006 5:28 AM
> > Subject: ***SPAM -- LOW *** [Dojo-interest] Documentation
> >
> > > Hi!
> > >
> > > I know this subject was discussed a hundred times before (I
> > > scanned the archives), but I want to share my thoughts ....
> > >
> > > I'm working for a software company in Germany and I'm looking for
> > > a JavaScript-Library to use in the project I'm working on at the
> > > moment.
> > >
> > > I found dojo and I personally think it is very good work, I
> > > really like it,
> > > especially dojo.io.bind and the "require" mechanism.
> > >
> > > Now I tried to use the widgets .... I think I must cease it and
> > > perhaps even
> > > cease the use of the toolkit because of the lack of
> > > documentation.
> > >
> > > The point is: of course I could make it with "trial and error",
> > > perhaps there is enough information in the interests group
> > > archives, and if I
> >
> > want
> >
> > > to use dojo for private purpose only I'm soure I would even enjoy
> > > it
> >
> > doing
> >
> > > it that way .... but as I want to use it on work, I just don't
> > > have time for
> > > things like that!
> > >
> > > I can't try, post in the forum, scan the archives, try again,
> > > post
> >
> > again,
> >
> > > wait again .... it's impossible to do this in a professional
> >
> > environment!
> >
> > > I really think the success of dojo in the near future will depend
> > > to
> >
> > some
> >
> > > (great) extent on the quality of the documentation .... what are
> > > all the great features worth if no one can find them?
> > >
> > > Again, I really, really like dojo and I will try to use it for
> > > one or
> >
> > two
> >
> > > more days, but I fear that I can't make progress fast enough in
> > > my
> >
> > boss's
> >
> > > opinion ....
> > >
> > > Regards,
> > > Jochen Zimmermann
> > >
> > > _______________________________________________
> > > Dojo FAQ: http://dojo.jot.com/FAQ
> > > [hidden email]
> > > http://dojotoolkit.org/mailman/listinfo/dojo-interest
> >
> > _______________________________________________
> > Dojo FAQ: http://dojo.jot.com/FAQ
> > [hidden email]
> > http://dojotoolkit.org/mailman/listinfo/dojo-interest

--
Alex Russell
[hidden email]
[hidden email] BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723
_______________________________________________
Dojo FAQ: http://dojo.jot.com/FAQ
[hidden email]
http://dojotoolkit.org/mailman/listinfo/dojo-interest
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation

Steve Sobol
Alex Russell wrote:
> We've looked at Doxygen, JSDoc, and any number of other JS documentation
> alternatives. They all suck for a language that's as dynamic as
> JavaScript. We have a new doc tool in the works that should fix most of
> the issues of JSDoc and Doxygen. The new system also doesn't require
> the grotty JavaDoc syntax for writing our documentation.

I've used XSLT and XML in the past. Works for generating many different
output formats...

--
Steve Sobol, Professional Geek   888-480-4638   PGP: 0xE3AE35ED
Company website: http://JustThe.net/
Personal blog, resume, portfolio: http://SteveSobol.com/
E: [hidden email] Snail: 22674 Motnocab Road, Apple Valley, CA 92307

_______________________________________________
Dojo FAQ: http://dojo.jot.com/FAQ
[hidden email]
http://dojotoolkit.org/mailman/listinfo/dojo-interest
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation

Alex Russell
On Sunday 12 March 2006 9:16 pm, Steve Sobol wrote:

> Alex Russell wrote:
> > We've looked at Doxygen, JSDoc, and any number of other JS
> > documentation alternatives. They all suck for a language that's as
> > dynamic as JavaScript. We have a new doc tool in the works that
> > should fix most of the issues of JSDoc and Doxygen. The new system
> > also doesn't require the grotty JavaDoc syntax for writing our
> > documentation.
>
> I've used XSLT and XML in the past. Works for generating many
> different output formats...

We've done that too. It's just that authoring it blows. We have a better
solution coming = )

Regards

--
Alex Russell
[hidden email]
[hidden email] BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723
_______________________________________________
Dojo FAQ: http://dojo.jot.com/FAQ
[hidden email]
http://dojotoolkit.org/mailman/listinfo/dojo-interest
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation

Wolfram Kriesing
So what is the solution that is coming going to look like?
Does it not even require inline comments?
Since I am working with dojo lately I am also spreading the
word and the first response is always that there is not
even inline docs. And I have to agree every time... it starts
to suck. If there was inline doc dojo would just be sooo much better
to use.

On 3/13/06, Alex Russell <[hidden email]> wrote:

> On Sunday 12 March 2006 9:16 pm, Steve Sobol wrote:
> > Alex Russell wrote:
> > > We've looked at Doxygen, JSDoc, and any number of other JS
> > > documentation alternatives. They all suck for a language that's as
> > > dynamic as JavaScript. We have a new doc tool in the works that
> > > should fix most of the issues of JSDoc and Doxygen. The new system
> > > also doesn't require the grotty JavaDoc syntax for writing our
> > > documentation.
> >
> > I've used XSLT and XML in the past. Works for generating many
> > different output formats...
>
> We've done that too. It's just that authoring it blows. We have a better
> solution coming = )
>
> Regards
>
> --
> Alex Russell
> [hidden email]
> [hidden email] BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723
> _______________________________________________
> Dojo FAQ: http://dojo.jot.com/FAQ
> [hidden email]
> http://dojotoolkit.org/mailman/listinfo/dojo-interest
>


--
cu

Wolfram
_______________________________________________
Dojo FAQ: http://dojo.jot.com/FAQ
[hidden email]
http://dojotoolkit.org/mailman/listinfo/dojo-interest
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation

iTorrey
Administrator
It will be inline

http://dojo.jot.com/Parser+Documentation



Wolfram Kriesing wrote:

> So what is the solution that is coming going to look like?
> Does it not even require inline comments?
> Since I am working with dojo lately I am also spreading the
> word and the first response is always that there is not
> even inline docs. And I have to agree every time... it starts
> to suck. If there was inline doc dojo would just be sooo much better
> to use.
>
> On 3/13/06, Alex Russell <[hidden email]> wrote:
>> On Sunday 12 March 2006 9:16 pm, Steve Sobol wrote:
>>> Alex Russell wrote:
>>>> We've looked at Doxygen, JSDoc, and any number of other JS
>>>> documentation alternatives. They all suck for a language that's as
>>>> dynamic as JavaScript. We have a new doc tool in the works that
>>>> should fix most of the issues of JSDoc and Doxygen. The new system
>>>> also doesn't require the grotty JavaDoc syntax for writing our
>>>> documentation.
>>> I've used XSLT and XML in the past. Works for generating many
>>> different output formats...
>> We've done that too. It's just that authoring it blows. We have a better
>> solution coming = )
>>
>> Regards
>>
>> --
>> Alex Russell
>> [hidden email]
>> [hidden email] BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723
>> _______________________________________________
>> Dojo FAQ: http://dojo.jot.com/FAQ
>> [hidden email]
>> http://dojotoolkit.org/mailman/listinfo/dojo-interest
>>
>
>
> --
> cu
>
> Wolfram
> _______________________________________________
> Dojo FAQ: http://dojo.jot.com/FAQ
> [hidden email]
> http://dojotoolkit.org/mailman/listinfo/dojo-interest
>
>
>
_______________________________________________
Dojo FAQ: http://dojo.jot.com/FAQ
[hidden email]
http://dojotoolkit.org/mailman/listinfo/dojo-interest
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documentation

Yi Tan
The solution for Polymorphism looks very interesting.

But I feel, since Javascript doesn't have argument constraints, in many cases, the function logic could be very flexible, and largely relys on the content of arguments rather then data type of arguments.

For example, following is a false script to attach a controller to a widget.

/*
the controller of my widget. It could be:
   string, widget id of an existing controller
   string, "off" my widget without a controller
   string, widget type, to create an instance of my widget with a specified controller widget
   object, the existing controller
   null, use default controller
*/
var controller;

function initialiseController() // no return.
{
   if(!this.controller) initialiseDefaultControll()
   else{
      if(isString(this.controller))
       {
          if(controller == "off")return
          else{
            var tmpCtrl = widget.byId(controller)
            if(tmpCtrl)this.controller = tmpCtrl
            else this.controller = createWidget(this.controller)
          }
       }else if(isObject(this.controller)) return
   }
}

Also, array in javascript doesn't have type definiation of its elements. And in many cases, it's very handy to have one function to deal with an arry of different types

something like

function appendNodeToMultipleParents(arraryOfParents, node)
{
    dojo.lang.Array.foreach(arr,
        function(item, node)
        {
           if(item.domNode)item.domNode.appendChild(node)
           else item.appendChild(node)
        }
    )
}

------------------------------------
I haven't found any software provides a solution to describe the flexbility of dynamic datatype in JavaScript. In other words, I think, perhaps, JavaDoc isn't a good solution for commenting JavaScript code.

I've been writting notes when studying dojo code. One trick I found very useful for myself is to forget the data type.

And so in the above two samples, I would like to write my comments of parameters like:

/*
string_widgetId, string_"off", string_widgetType, object_widgetInstance, null_defaultController
*/
var controller;

function appendNodeToMultipleParents(
/*
  array_of_domNode : a list of parent nodes ,
  array_of_widget : a list of widget instances
*/
arraryOfParents,
/*object_domNode : the dom node*/
node
)

I think it will be wonderful, if the new dojo documanation parser can understand these comments, and outputs the document like

Parameters:
arraryOfParents
    Accepectable datatype:
    - array_of_domNode
      a list of parent nodes
    - array_of_widget
      a list of widget instances

Regards,

Yi


On 3/31/06, Torrey Rice <[hidden email]> wrote:
It will be inline

http://dojo.jot.com/Parser+Documentation



Wolfram Kriesing wrote:

> So what is the solution that is coming going to look like?
> Does it not even require inline comments?
> Since I am working with dojo lately I am also spreading the
> word and the first response is always that there is not
> even inline docs. And I have to agree every time... it starts
> to suck. If there was inline doc dojo would just be sooo much better
> to use.
>
> On 3/13/06, Alex Russell <[hidden email]> wrote:
>> On Sunday 12 March 2006 9:16 pm, Steve Sobol wrote:
>>> Alex Russell wrote:
>>>> We've looked at Doxygen, JSDoc, and any number of other JS
>>>> documentation alternatives. They all suck for a language that's as
>>>> dynamic as JavaScript. We have a new doc tool in the works that
>>>> should fix most of the issues of JSDoc and Doxygen. The new system
>>>> also doesn't require the grotty JavaDoc syntax for writing our
>>>> documentation.
>>> I've used XSLT and XML in the past. Works for generating many
>>> different output formats...
>> We've done that too. It's just that authoring it blows. We have a better
>> solution coming = )
>>
>> Regards
>>
>> --
>> Alex Russell

>> [hidden email]
>> [hidden email] BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723
>> _______________________________________________
>> Dojo FAQ: http://dojo.jot.com/FAQ
>> [hidden email]
>> http://dojotoolkit.org/mailman/listinfo/dojo-interest
>>
>
>
> --
> cu
>
> Wolfram
> _______________________________________________
> Dojo FAQ: http://dojo.jot.com/FAQ
> [hidden email]
> http://dojotoolkit.org/mailman/listinfo/dojo-interest
>
>
>
_______________________________________________
Dojo FAQ: http://dojo.jot.com/FAQ
[hidden email]
http://dojotoolkit.org/mailman/listinfo/dojo-interest


_______________________________________________
Dojo FAQ: http://dojo.jot.com/FAQ
[hidden email]
http://dojotoolkit.org/mailman/listinfo/dojo-interest
Loading...