WARNING: Can't augment contributer error when docs are correct

[GoogleCodeExporter]

I'm not 100% sure I understand the problem but... see below

What steps will reproduce the problem?
1. Run the file below through jsdoctookit.  Here is my command line.

java.exe -Djsdoc.dir=jsdoctoolkit/files -jar jsdoctoolkit/files/jsrun.jar
jsdoctoolkit/files/app/run.js -v -t=jsdoctoolkit/files/templates/jsdoc//
-d=test test.js

2. I get an error

>> WARNING: Can't augment contributer: , not found.

It looks like line 209 of SymbolSet.js

 var contributer = this.getSymbol(augments[i]);

should be this?

 var contributer = this.getSymbol(augments[i].type);

Whether that's a real issue or I'm doing something wrong I'm not aware. If
my change is correct, I'm also not sure if any of the lines below that need
to be changed similarly

Original issue reported on code.google.com by g...@google.com on 22 Apr 2009 at 2:00

[GoogleCodeExporter]

I can't effectively evaluate this report with seeing the code that you are 
trying document causing this error.

var contributer = this.getSymbol(augments[i]); appears to be correct.

Original comment by micmath on 15 Jun 2009 at 3:23

• Changed state: MoreInfoRequired

[GoogleCodeExporter]

Sorry, Basically make a class

/**
 * Module.
 * @namespace
 */
var module = {};

/**
 * Base Class.
 * @constructor
 */
Module.Base = function() {
  // ...
};

/**
 * Derived Class.
 * @extends {Module.Base}
 */
Module.Derived = function() {
  // ...
};

Then run it through jsdoctoolkit

I get an error with the current release. If I change SymbolSet.js as shown 
above I
stop getting the error and I get what appears to be the correct result.

Original comment by g...@google.com on 15 Jun 2009 at 5:25

[GoogleCodeExporter]

Some more info. First, change "var module" above to "var Module" then run
jsdoctoolkit with the commandline listed in the first message. I get this 
warning

 > JsDoc Toolkit main() running at Tue Jun 16 2009 02:37:08 GMT+0900 (JST).
 > With options: 
 >     d: test
 >     t: jsdoctoolkit/files/templates/jsdoc/
 >     _: test.js
 >     v: true
 > Output directory set to 'test/'.
 > Parsing file: test.js
>> WARNING: Can't augment contributer: , not found.
1 warning.

Make the suggested change and that warning goes away and my docs show the 
correct
inheritance.

Original comment by g...@google.com on 15 Jun 2009 at 5:39

[GoogleCodeExporter]

If you can get the output you want with the modification you suggest that is 
merely a coincidence, probably a 
rare case where two wrongs make a right. But I'd recommend you leave the source 
for JsDoc Toolkit as it is 
and simply correct your documentation comments, as two rights will also make a 
right.

The wiki has a page for @augments (which @extends is a synonym for) and it 
states that the correct syntax is:
`@augments otherClass`
otherClass - Required: the namepath to the class this one augments.

So you should be writing "@extends Module.Base", not "@extends {Module.Base}" 
(note that the curly braces 
are unneeded and incorrect here). Additionally you need to add a @constructor 
or @namespace tag to the 
comment for Module.Derived. I've made these changes (shown below) and got the 
desired output.

/**
 * Module.
 * @namespace
 */
Module = {};

/**
 * Base Class.
 * @constructor
 */
Module.Base = function() {
  // ...
};

/**
 * Derived Class.
 * @constructor
 * @extends Module.Base
 */
Module.Derived = function() {
  // ...
};

see:
    http://code.google.com/p/jsdoc-toolkit/wiki/TagAugments
    http://code.google.com/p/jsdoc-toolkit/wiki/NamePaths

Original comment by micmath on 20 Jun 2009 at 4:30

• Changed state: Invalid

[GoogleCodeExporter]

Why the inconsistency with the @param tag? Why do types in the @param tag need 
a {}
but types in @type and @extends don't?

Original comment by g...@google.com on 20 Jun 2009 at 5:16

[GoogleCodeExporter]

If you look at the syntax for @param tag, consider these possible variants:

@param name here is a description.
@param type name here is a description.

Pretend you are a dumb computer and don't understand natural language: how 
would you find the "type" in 
the second example but not the first? That first example might have a type of 
"name" and a name of "here". 
There needs to be some additional syntax added to say, "this word is a type and 
not a name", and conversly 
"this is a name, not a type", the {braces} or lack of braces are that syntax.

For example, with braces it would now be obvious that the first has no type, 
but the second one does:

@param name here is a description.
@param {type} name here is a description.

It is @param that is the odd one here because it *optionally* allows a type in 
a spot that could just as easily 
contain a name.

@extends by contrast must always have only a type. Forcing people to add braces 
there would be redundant, 
same with @type.

Original comment by micmath on 22 Jun 2009 at 8:32