Javascript Documentation

[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

[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
--
Evertjan.
The Netherlands.
(Please change the x'es to dots in my emailaddress)

[Dr John Stockton]

JRS: In article <3f********************************@4ax.com>, seen in
news:comp.lang.javascript, Kent Feiler <zz**@zzzz.com> posted at Sun, 2
May 2004 06:12:01 :

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.

--
© John Stockton, Surrey, UK. ?@merlyn.demon.co.uk Turnpike v4.00 IE 4 ©
<URL:http://jibbering.com/faq/> Jim Ley's FAQ for news:comp.lang.javascript
<URL:http://www.merlyn.demon.co.uk/js-index.htm> jscr maths, dates, sources.
<URL:http://www.merlyn.demon.co.uk/> TP/BP/Delphi/jscr/&c, FAQ items, links.

[Matt Kruse]

"Kent Feiler" <zz**@zzzz.com> wrote:

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/...st/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/...ct_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.

--
Matt Kruse
Javascript Toolbox: http://www.mattkruse.com/javascript/

[Thomas 'PointedEars' Lahn]

Kent Feiler wrote:

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 try to keep JSdoc[1] short and serve it unchanged for others to use the
source code if they want.
PointedEars
___________
[1] <http://pointedears.de/scripts/JSdoc/>