Provide small example JS files in the jsdoc distribution

[GoogleCodeExporter]

Perhaps this is just me, but I'm finding it very difficult to get started 
with jsdoc.  I'd like to suggest that you include a sample JS file in the 
jsdoc-toolkit distribution (that could be referenced from README.txt), and 
maybe create a simple "Getting Started" page on Google Code.

As an example of the trouble I'm having, I'm trying to generate 
documentation for the file test.js:

var foo = { };

/**
 * Converts a wizzle to a wozzle.
 *
 * @example
 * foo.convert("ffff");
 *
 * NOTE: Only works if the wizzle is less than 100 characters long.
 * 
 * @param {String} s string to convert
 * @return {String}
 */

 foo.convert = function(s) {
   return "jjj";
 };

However, if I run jsdoc-toolkit with the command line

java -jar jsrun.jar app/run.js -a -t=templates/jsdoc test.js

I get some generated files in the "out" directory, but there's no actual 
generated documentation.  It's quite likely that there's some sort of 
syntax error in my file, but it would be useful if there were a guaranteed-
to-work sample.js in the distribution that I can expect to work.

I tried adding @name and @function tags as mentioned in the FAQ, but this 
didn't make any difference.  Replacing the body with

function helloWorld() {
  alert('Hello, World');
}

did produce documentation, but I'm unsure why my test file produces 
nothing.

Would it be possible to include a sample.js that incorporates a few 
examples of different tags, and incorporate this into the "USAGE" section 
of README.txt?

Original issue reported on code.google.com by ithinkihaveacat on 4 Dec 2009 at 10:38

[GoogleCodeExporter]

When I say generating documentation for test.js doesn't work, I mean that files 
are 
generated in the "out" directory, and the "File Index" lists test.js, but I 
can't find 
any documentation for foo.convert on the "Built-In Namespace _global_" page or 
anywhere 
else.  (I suppose I would have expected a "foo" namespace page to be generated.)

Original comment by ithinkihaveacat on 4 Dec 2009 at 10:44

[GoogleCodeExporter]

I'm sorry you are having trouble getting started. I'm writing a fairly complete 
"Getting Started" tutorial right 
now actually, but if you take a look at the output from running your example 
code above you should see that 
JsDoc Toolkit is trying to tell you what the problem is:

  >> WARNING: Trying to document convert as a member of undocumented symbol foo.

This means you are adding documentation for the method named 'convert' before 
you've documented it's 
parent 'foo'. It's easy to fix, just document 'foo'. The following should 
produce no warnings:

/** @namespace */
var foo = { };

/**
 * Converts a wizzle to a wozzle.
 *
 * @example
 * foo.convert("ffff");
 *
 * NOTE: Only works if the wizzle is less than 100 characters long.
 * 
 * @param {String} s string to convert
 * @return {String}
 */
 foo.convert = function(s) {
   return "jjj";
 };

Original comment by micmath on 5 Dec 2009 at 10:39

• Changed state: WontFix

[GoogleCodeExporter]

Please consider making this an error instead of a warning, since otherwise it 
seems a 
bit odd that otherwise valid documentation is tossed away.  My reaction to the 
warning 
was "Yes, I know I didn't document that, I'll get around to it later."

(This is slightly a side effect of me using closure and I'm not actually sure 
*how* to 
document it, since the namespace is implied by goog.provide / goog.require.  
I'm trying 
to avoid pulling in the closure sources into my docs, but nothing else 
describes the 
namespace)

Original comment by jeffbailey@google.com on 2 Jan 2010 at 8:46

[GoogleCodeExporter]

I'm not certain this is an error. In fact the documentation is not "tossed 
away" but you are setting up a 
situation where you cannot ever get to the documentation.

If you think of the set of symbols in your documentation as a tree, with the 
_global_ "class" at the base, the 
expectation is that every symbol you document will be on a branch that 
eventually connects back to _global_. 
However if you start documenting a method "foo" on class "non.Existent," when 
there is no documentation for 
"non.Existent" then there is no way to get to the branch that foo is on. The 
documentation still exists however. 
You can prove so by doing the following (pay attention to the "vampire" 
method)...

----

// with thanks to www.daveoncode.com for this example

goog.provide("com.jsmonstersbattle.monsters.Monster");

/**
 * A common Monster
 * @constructor
 * @param {String} name
 * @param {String} age
 * @param {Number} level
 * @borrows com.jsmonstersbattle.weapons.RayGun.sap as this.vampire
 */
com.jsmonstersbattle.monsters.Monster = function(name, age, level) {
}

/**
* Returns an amount of damage points
* @return {Number}
*/
com.jsmonstersbattle.monsters.Monster.prototype.attack = function() {
}

goog.provide("com.jsmonstersbattle.weapons.RayGun");

/**
 * Reduce a target's level.
 * @function
 * @param target
 */
com.jsmonstersbattle.weapons.RayGun.sap = function(target) {
}

----

Here we see that the documentation for com.jsmonstersbattle.weapons.RayGun.sap 
exists: it must because it 
can successfully be borrowed by com.jsmonstersbattle.monsters.Monster. The only 
problem is there won't be 
any link to com.jsmonstersbattle.weapons.RayGun in the class listing, because 
it is never documented as 
being a class. For all JsDoc Toolkit knows RayGun might be a String Object, or 
a RegExp Object, it won't just 
arbitrarily decide that RayGun will be documented as a constructor function or 
a namespace object, even 
though it appears to you and I that it *probably* is one of those things.

So things will still work with the warning, nothing is being discarded or 
broken, you're just doing something 
that's quite suspect, and is *probably* not what you meant. I'm leaning towards 
leaving this as a warning. 
However, if you propose to the user list changing this to an error, I might be 
swayed by the community.

Original comment by micmath on 2 Jan 2010 at 12:57