Proper Script/Code Documentation

I am looking for standards or advice or guidelines, either written in a
posted reply here or given by a link in your reply, that gives CONVENTIONAL
or TRADITIONAL or ACCEPTED-STANDARD formatting for how to document
script/code. My guess is also that this is used by automatic
documentation-gathering software tools.

I have a fair idea that classes/functions should be described at a minimum
as to purpose, parameters passed, and return value(s). But there is a lot
of other symbols/characters used, including how "to version" the code.

With descriptions (with multiple paragraphs similar to UNIX documentation),
I tend to put them at the bottom of a *.js file between /* */ delimiters,
with a line at the top directing the reader to the bottom of the script
file.

What are everyone's (best?) practices here?

How do you avoid the problem of coming back to YOUR OWN code months later
and trying to figure out what you were doing, let alone having another
developer come to your code and instantly picking up the ball and running
with it?

On Mon, 25 Aug 2008 at 11:46:32, in comp.lang.javascript, Patient Guy
wrote:If you're using software tools you won't have much choice. You'll just
have to learn to live with whichever format rules you don't like.

Keep it simple, keep it clear, don't neglect it, and, above all, keep it
up to date. That last one is easier if you've kept it simple and clear.

Surely the best two choices are to put a function's specification inside
the function or in a separate document. Anywhere else will be more
trouble to read, write, and update.

This works for me :

function Vet(form)
// Vet the form and return true iff values are ok
{ ... }

And so does this :

function DayName(dow)
// Return name for day of week dow (English)
// In and Pre
// dow : Integer
// Out and Post
// DayName : String
// DayName is name of day dow if 0 <= dow <= 6
// DayName is "<unknown>" otherwise
{ ... }


John
--
John Harris

On 25 Aug., 18:46, Patient Guy <sevisen.adam@gmailDOTHEREcomwrote:Check out JsDoc Toolkit (http://jsdoctoolkit.org/). You can comment
your sources using the JsDoc syntax (it's like Javadoc) and than
generate documentation running JsDoc Toolkit from commandline.

Regards,
purcaholic