Better message when invalid tags paired with @fileoverview

[GoogleCodeExporter]

What steps will reproduce the problem?
1. Unpack the attached ZIP file.
2. Try to document both of the files. I'm using the following config file:

---------------------------------------------------------------------
{
    // source files to use
    _: ['path/to/file/Character_Rigger_v05.js', 'path/to/file/CR_UI.js'],

    // document all functions, even uncommented ones
    a: true,

    // including those marked @private
    p: true,

    // some extra variables I want to Include
    D: {generatedBy: "Collin Brooks", copyright: "2009"},

    // use this directory as the output directory
    d: "docs",

    // use this template
    t: "templates/jsdoc",

    //Be verbose
    v: true,

    //Recurse n many directories
    r: 0

}

---------------------------------------
3. Run this command in the root jsdoc toolkit directory:

java -jar jsrun.jar app/run.js -c=conf/CR.conf

What is the expected output? What do you see instead?

The expected output is obviously a correctly documented file. Instead, I
get the following warnings: 

WARNING: Trying to document js as a member of undocumented symbol
/path/to/file/CR_UI.
>> WARNING: Sorry, that doesn't seem to be a valid template:
templates/jsdoc/publish.js : JavaException: java.io.FileNotFoundException:
docs/symbols/path/to/file/CR_UI.js.html (No such file or directory)
2 warnings.

What version of the product are you using? On what operating system?

jsdoc_toolkit-2.3.2 on Mac OS X

Please provide any additional information below.

Looking at the warning, it looks as if the parser is setting
"/path/to/file/CR_UI" as a symbol and trying to "js" as a memeber of it.

These Javascript files are used within Adobe After Effects and therefore do
not use the normal DOM to access objects.

Is there something wrong in my source code that is causing the parser to go
crazy?

Original issue reported on code.google.com by collin.b...@gmail.com on 3 Jan 2010 at 5:55

Attachments:

• jsdocTest.zip

[GoogleCodeExporter]

The parser isn't crazy. The trouble is coming from the file named CR_UI.js. 

Here's the explanation: Any doc comment that contains a @fileoverview tag is 
considered to be 
documentation for a "file object", which has the @name implicitly set to the 
file pathname for that file. So, in 
the CR_UI.js file, there is file object named "/path/to/file/CR_UI.js". That 
much is fine and as expected. The 
problem comes when you then add a @constructor tag to the same comment. This is 
not allowed. Really JsDoc 
Toolkit should throw an error telling you something like "No, no. You can 
document a file or you can 
document a constructor, but you can't do both at once! Use separate comments 
please!" But instead it carries 
on, according to your @constructor tag, but still using the leftover @name tag 
from before, and logically 
concludes you mean to document a constructor named "/path/to/file/CR_UI.js". 
The rest is as you observed.

The short answer: you need to break that comment up into two separate comments!

I'll leave this report as "accepted" meaning the error message should be more 
useful.

Original comment by micmath on 3 Jan 2010 at 7:10

• Changed title: Better message when invalid tags paired with @fileoverview
• Changed state: Accepted
• Added labels: Type-Enhancement