Rails spinoffs - Aug 2005 - Documentation generator?

I''m looking for a documentation generator for JavaScript code that can 
handle the coding style used in prototype.js and script.aculo.us. Any 
recommendations for such a tool?

In a similar vein, does it make a noticeable difference in production 
when comments are removed and several script files are combined into a 
single one?

Michael

-- 
Michael Schuerig               Most people would rather die than think.
mailto:michael@schuerig.de                            In fact, they do.
http://www.schuerig.de/michael/                      --Bertrand Russell

On 01/09/2005, at 9:12 AM, Michael Schuerig wrote:
> In a similar vein, does it make a noticeable difference in production
> when comments are removed and several script files are combined into a
> single one?
Well it means smaller size and a single http request, and when combined 
with output compression I''d imagine a significant decrease in download 
time. Currently it weighs in at 4 files totalling around 400KB doesn''t 
it?

When I get to it I was planning on writing a SwitchTower task that 
chomps the JS files on deployment to production servers... it''ll just 
concat them in the right order and chomp whitespace etc to a single 
file. This is only possible now that (I hope) in the next version 
javascript_include_tag :defaults will only be referring to a single 
file.

-- tim lucas

> In a similar vein, does it make a noticeable
> difference in production 
> when comments are removed and several script files
> are combined into a 
> single one?
The short answer is: yes.  The long answer is ''it
depends''.

Having multiple files creates an initial latency hit
no matter what you do.  If you have a site like one of
mine where lots of non-repeat users visit, you''d like
to minimize the initial latency hit as much as
possible.  One big compressed file works best.

For sites and applications where the user returns
frequently, you can send headers to enable long-term
browser caching.  Then with multiple files that will
reduce the subsequent latency hit and reload hit.

The only downside of browser caching is that if you
update the javascript to fix a bug/release a new
version, the new versions won''t be downloaded until
the old cached copies expire.

To be slightly more clever, you might try a cache
buster URL (append ''?cache_buster=1'' or the like to
the url) that you increment each time you release a
new version of the javascript files.  You''d have to
bypass the Rails javascript helpers in that case and
roll your own.

Now what I''d love to see is lots more comments/in-line
docs in scriptaculous - we could feed them through the
Dojo compressor for stripping before release (see P.S.
below).

My 2c,

-San

P.S. If you''d like a good Javascript compressor, the
folks over at Dojo just released theirs into the wild.
 Dojo also serves as a great example of how to
distribute a js toolkit in various single-file sizes:

http://dojotoolkit.org/docs/compressor_system.html











> 
> Michael
> 
> -- 
> Michael Schuerig               Most people would
> rather die than think.
> mailto:michael@schuerig.de                          
>  In fact, they do.
> http://www.schuerig.de/michael/                     
> --Bertrand Russell
> _______________________________________________
> Rails-spinoffs mailing list
> Rails-spinoffs@lists.rubyonrails.org
>
http://lists.rubyonrails.org/mailman/listinfo/rails-spinoffs
> 

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com

> P.S. If you''d like a good Javascript compressor, the
> folks over at Dojo just released theirs into the wild.
>  Dojo also serves as a great example of how to
> distribute a js toolkit in various single-file sizes:
Dojo is brilliant, significantly reduced the sizes of many of the
Javascripts we have in production.

Best thing about it is that unlike many similar tools which work by
using regular expressions etc, this one uses the Rhino JS parser
thingy so you don''t find that it breaks your scripts!

Kind Regards
Chris

On 01/09/05, Chris Korhonen <ckorhonen@gmail.com> wrote:
> Dojo is brilliant, significantly reduced the sizes of many of the
> Javascripts we have in production.
If you want even more compression with methods Dojo does not use,
check http://jscompact.sourceforge.net/ . It also uses Rhino.

Bye,
  Martin

Did dojo work for u against dragdrop.js ?
I am getting a javascript error with the compressed
version. Howeve it did a great job with others JS
scripts !

Martin,

did jscompact work for u ?
Rgds-Claude


--- Martin Bialasinski <klingeling@gmail.com> wrote:
> On 01/09/05, Chris Korhonen <ckorhonen@gmail.com>
> wrote:
> 
> > Dojo is brilliant, significantly reduced the sizes
> of many of the
> > Javascripts we have in production.
> 
> If you want even more compression with methods Dojo
> does not use,
> check http://jscompact.sourceforge.net/ . It also
> uses Rhino.
> 
> Bye,
>   Martin
> _______________________________________________
> Rails-spinoffs mailing list
> Rails-spinoffs@lists.rubyonrails.org
>
http://lists.rubyonrails.org/mailman/listinfo/rails-spinoffs
> 

Claude Hussenet
Independent J2EE Architect Consultant
http://claudehussenet.com


		
____________________________________________________
Start your day with Yahoo! - make it your home page 
http://www.yahoo.com/r/hs

Claude Hussenet wrote:
> Did dojo work for u against dragdrop.js ?
> I am getting a javascript error with the compressed
> version. Howeve it did a great job with others JS
> scripts !
I had the same issue, running into errors after dojo compressing them. I 
think it''s that it takes "internal" variables for the objects
created
and converts them to names like _52 from options which then breaks calls 
to the objects from other places. Maybe it''s got to do with the coding 
style of script.aculo.us, not sure, but that type of compression
doesn''t
seem to be good for it.

Perhaps "compressed" versions of the files could be automatically 
created when changes are committed so we can grab the appropriate 
versions for our needs.


Oh, when I was playing with this, I decided that I wanted to change the 
names of the files to have a prefix of "c_" to give me a visual clue
to
which files to work with, I ten needed to go into scriptaculous.js to 
change the file names, and had a though. Was wondering if the file names 
to require should be in an array and then looped over that array to 
include into the page.

I also see that the for loop checking for the scriptaculous.js file name 
in the script src doesn''t break when it is found (unless there is a 
reason to continue checking). So here is my proposed newer version of 
Scriptaculous (watch for line breaks caused by my mail client):


Scriptaculous = {
   Version: ''1.5_pre4_trunk'',
   require: function(libraryName) {
     // inserting via DOM fails in Safari 2.0, so brute force approach
     document.write(''<script type="text/javascript" 
src="''+libraryName+''"></script>'');
   },
   load: function() {
     // fixme: check for prototype version number
     if(typeof Prototype==''undefined'')
       throw("script.aculo.us requires the Prototype JavaScript 
framework >= 1.4.0");
	var requires =
[''util.js'',''effects.js'',''dragdrop.js'',''controls.js''];
     var scriptTags = document.getElementsByTagName("script");
     for(var i=0;i<scriptTags.length;i++) {
       if(scriptTags[i].src && 
scriptTags[i].src.match(/scriptaculous\.js$/)) {
         var path =
scriptTags[i].src.replace(/scriptaculous\.js$/,'''');
		var j=0;
		while(j<requires.length){
			this.require(path + requires[j++]);
		}
	break;
       }
     }
   }
}

Scriptaculous.load();


A couple of other thoughts:
1. Should the if(typeOf Prototype==''undefined'')  also do a
check for the
Ptototype.Version property to ensure it runs fine, as Prototype 1.3 
could pass this test, right?

2. Maybe check would be to see if the file has already been "required"
so that a reference to it isn''t duplicated/overwritten. Probably not 
much of an issue, but with sites that may need multiple server side 
include files could be an issue.



-- 
Danilo Celic
| Extending Knowledge Daily : http://CommunityMX.com/
| Team Macromedia for Dreamweaver : http://macromedia.com/go/team/

On 9/2/05, danilocelic <danilo@shimmerphase.com>
wrote:
> 
> Claude Hussenet wrote:
> > Did dojo work for u against dragdrop.js ?
> > I am getting a javascript error with the compressed
> > version. Howeve it did a great job with others JS
> > scripts !
> 
> I had the same issue, running into errors after dojo compressing them. I
> think it''s that it takes "internal" variables for the
objects created
> and converts them to names like _52 from options which then breaks calls
> to the objects from other places. Maybe it''s got to do with the
coding
> style of script.aculo.us <http://script.aculo.us>, not sure, but that
type
> of compression doesn''t
> seem to be good for it.
> 
As someone else mentioned, http://jscompact.sourceforge.net/ is another good 
javascript compressor, and I didn''t have any problems when I used it on
the
prototype library.
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://wrath.rubyonrails.org/pipermail/rails-spinoffs/attachments/20050902/e2b4d8dd/attachment.html

> Oh, when I was playing with this, I decided that I wanted to change  
> the names of the files to have a prefix of "c_" to give me a
visual
> clue to which files to work with, I ten needed to go into  
> scriptaculous.js to change the file names, and had a though. Was  
> wondering if the file names to require should be in an array and  
> then looped over that array to include into the page.
>
> I also see that the for loop checking for the scriptaculous.js file  
> name in the script src doesn''t break when it is found (unless
there
> is a reason to continue checking). So here is my proposed newer  
> version of Scriptaculous (watch for line breaks caused by my mail  
> client):
I''ve added the break to the latest tunk.
Note that i''ve not included the array-based approach for now as there  
will be afaik some nice new extensions to the Array class in the next  
prototype release, which I hope to incorporate in all of  
script.aculo.us.

Thomas

On Friday 02 September 2005 23:13, Dillon Woods wrote:
> As someone else mentioned, http://jscompact.sourceforge.net/ is
> another good javascript compressor, and I didn''t have any problems
> when I used it on the prototype library.
Has anyone by chance measure the impact compression has? Under what 
circumstances is it noticeable?

Michael

-- 
Michael Schuerig                      They tell you that the darkness
mailto:michael@schuerig.de                  Is a blessing in disguise
http://www.schuerig.de/michael/           --Janis Ian, From Me To You

On a single file it''s not a huge win.  The connection
latency just to get the file usually dwarfs the
transfer time.  More files = more latency.  Slow link
= really awful startup time.

I think it would be a big win if we concat everything
(all the *.js including prototype) into one big
''scriptaculous_full.js'' and compress that.

Then we''d nail the latency issue and transfer time in
one swoop.

Any thoughts on adding a concat/jscompress pass to the
release process?  (Thomas?)

Basically we''d be following prototype''s release
process (multiple source files produce one output
file) with an added jscompress pass.  And with
JScompress in the loop we could comment scriptaculous
source with wild abandon and not worry about bloating
the distribution code.

-San

--- Michael Schuerig <michael@schuerig.de> wrote:
> On Friday 02 September 2005 23:13, Dillon Woods
> wrote:
> > As someone else mentioned,
> http://jscompact.sourceforge.net/ is
> > another good javascript compressor, and I didn''t
> have any problems
> > when I used it on the prototype library.
> 
> Has anyone by chance measure the impact compression
> has? Under what 
> circumstances is it noticeable?
> 
> Michael
> 
> -- 
> Michael Schuerig                      They tell you
> that the darkness
> mailto:michael@schuerig.de                  Is a
> blessing in disguise
> http://www.schuerig.de/michael/           --Janis
> Ian, From Me To You
> _______________________________________________
> Rails-spinoffs mailing list
> Rails-spinoffs@lists.rubyonrails.org
>
http://lists.rubyonrails.org/mailman/listinfo/rails-spinoffs
> 

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com

Dillon Woods wrote:
> As someone else mentioned, http://jscompact.sourceforge.net/ is another 
> good javascript compressor, and I didn''t have any problems when I
used
> it on the prototype library.
Looks like you have to build from source and you require several other 
bits of code to compile with. Too much for me to worry about at this 
time, but I''ll keep in on the list for later.

Danilo