Javascript Documentation

K

Kent Feiler

As an old-time C programmer, I'm used to placing program documentation
in the program. No problem there since it all goes away when the
executable is created. Using the same technique in Javascript though,
has the serious disadvantage that all your wonderful Doc has to be
downloaded and adds to the page loading overhead. So...I was
wondering how you all handle that situation.



Regards,


Kent Feiler
www.KentFeiler.com
 
E

Evertjan.

Kent Feiler wrote on 02 mei 2004 in comp.lang.javascript:
As an old-time C programmer, I'm used to placing program documentation
in the program. No problem there since it all goes away when the
executable is created. Using the same technique in Javascript though,
has the serious disadvantage that all your wonderful Doc has to be
downloaded and adds to the page loading overhead. So...I was
wondering how you all handle that situation.

On an asp server, you can remark serverside:

============= remarkable_js.asp =============

<script type="text/javascript">
var a = 1 //<% ' initializing a %>
a++ //<% ' incrementing a %>
alert(a) //<% ' showing the resulting value of a %>
</script>

the // allows local direct browser testing
 
D

Dr John Stockton

JRS: In article <[email protected]>, seen in
As an old-time C programmer, I'm used to placing program documentation
in the program. No problem there since it all goes away when the
executable is created. Using the same technique in Javascript though,
has the serious disadvantage that all your wonderful Doc has to be
downloaded and adds to the page loading overhead. So...I was
wondering how you all handle that situation.

I do not, since the comment in my stuff is intended to be seen.

However, here's a thought.

If you restrict your "excessive" commenting to start with, say, /// at
the beginning of each line, and restrict your HTML not to so start, then
you can easily have a little program that will strip excessive
commenting from your working master copy to make your distribution copy.

My editor preserves all whitespace; I have a batch file to remove
trailing whitespace from HTML files; I estimate that using it reduces my
average page size by o(1%), which for the trivial effort involved is
worthwhile.

Leading whitespace can be removed if <pre> ... </pre> is not used.

Such techniques can be extended.
 
M

Matt Kruse

Kent Feiler said:
Using the same technique in Javascript though,
has the serious disadvantage that all your wonderful Doc has to be
downloaded and adds to the page loading overhead. So...I was
wondering how you all handle that situation.

I actually have 3 versions of each script that I have which I put up on my
website.

I have a local version which is liberally commented and has a lot of debug
statements and "assert" kind of statements.
After development is done and I've tested, I run a script which removes all
the debug code and any debug comments, which I mark with //DEBUG:

Then I upload to my website, and I have code like what you see at:
http://www.mattkruse.com/javascript/dynamicoptionlist/source.html

This is full code, commented, and with documentation included in the source
file. This is meant for learning the interface and seeing how the code
works. In this example, the code is 24k - fairly hefty. Once a person is
familiar with the library and is ready to include it into their working
site, they download and use the "compact" version of the code:
http://www.mattkruse.com/javascript/dynamicoptionlist/compact_source.html .
This has comments and whitespace removed, and is better for using in the
real-world situation where reducing js file size might be important because
it is _half_ the size.

I use a perl script which I wrote to do this. It's a messy hack, but it
works. In my local testing, I test with the compact version of the code to
make sure that nothing has been broken during the compression.

There are scripts and utilities out there to compress javascript by removing
whitespace and such - some searching will surely find one that fits your
needs.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Similar Threads


Members online

Forum statistics

Threads
473,744
Messages
2,569,482
Members
44,901
Latest member
Noble71S45

Latest Threads

Top