Documentation of meta tags incorrect

[GoogleCodeExporter]

What steps will reproduce the problem?
See the test file's /**@+ block for an example.

What is the expected output? What do you see instead?
- Expect: Meta tag content duplicated across the apis within meta tag bookends.

- Observe:  Meta tags don’t work within the return statement of a namespace
that uses the “Module Pattern.” Content is not duplicated and APIs 
undocumented

- Workaround:  We just duplicated the tags instead of taking advantage of
meta-tagging.

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

OS:  Windows XP with Firefox

The site shown in clientapi_docs.zip was produced by a snapshot of
jsdocs-toolkit v2 downloaded about a week ago.   The JsDocTookKitIssues.js
test file was written to the most recent beta build downloaded this
evening, but this build doesn’t work well with our clientapi_docs.

All docs were run using a command line that looked something like this,
where the .js files were in the labkey\Test directory:

java –jar jsrun.jar app\run.js labkey\Test –t=templates\jsdoc –a

Please provide any additional information below.

I’ve attached a test file called JsDocToolkitIssues.js to demo many of
these potential issues, plus clientapi_docs.zip to show you our finished
site for LabKey Server v8.1. 

Note 1:  Our APIs use the “Module Pattern” described here: 
http://www.klauskomenda.com/code/javascript-programming-patterns/#module

Note 2:  Our APIs are client-side, javascript wrappers around server-side
APIs described here:
https://www.labkey.org/wiki/home/Documentation/page.view?name=remoteAPIs .
 This means that some of the objects users need to know about to use the
client APIs are actually defined only in the server-side code.  We don’t
yet have the server-side code annotated & doc’ed, so we had to get a bit
creative to generate any sort of documentation for these objects.  We’ve
doc’ed these mysterious objects by creating namespaces for them. This is
the root of many of the issues I'm entering.  Better ideas for getting
these objects doc’ed are welcome – we’re not set on our current strategy
for future docs.

Original issue reported on code.google.com by ekaynel...@gmail.com on 26 Mar 2008 at 9:23

Attachments:

• clientapi_docs.zip
• JsDocToolkitIssueTest.zip

[GoogleCodeExporter]

This bug is not in the code, rather it's in the documentation. I'm embarrassed 
to
say, this was just a stupid mistake on my part when writing the wiki page on 
meta
tags. I've corrected the Version 2 wiki page now:
http://www.jsdoctoolkit.org/wiki/index.php?page=Meta+Tags

The Version 1 wiki has always been correct, by the way, it is listed under the
heading "Shared Doclets" here:
http://code.google.com/p/jsdoc-toolkit/wiki/DocExamples

Anyway, you just need to add an octothorp to make it work: /**#@+ and /**#@-*/

Original comment by micmath on 30 Mar 2008 at 1:00

• Changed title: Documentation of meta tags incorrect
• Changed state: Fixed

[GoogleCodeExporter]

Thwarted by the octothorp again!  I should have noticed the difference between 
the
two versions of the docs.

Unfortunately, adding the octothorp to the begin/end meta tags does not fix the
problem.  I've attached a simple repro.  Perhaps I've misunderstood usage of 
the tags?

I would expect duplication of the @param definitions for all three methods.  
The one
exception would be the one locally-defined @param tag for 'successCallback' for
'deleteRows,' which I would expect to override the @param meta tag for 
'successCallback.'

Thanks for taking a look when you get a chance.

Original comment by ekaynel...@gmail.com on 30 Mar 2008 at 8:54

Attachments:

• MetaTagTest.js

[GoogleCodeExporter]

Hello and thanks for you example code -- it really helps. My working copy gives 
the
following result from your MetaTagTest.js file:

  http://jsdoctoolkit.org/scratch/MetaTagTest/

I believe this is the desired result you are describing. If so (please 
confirm), the
fix will be in the next release.

Original comment by micmath on 31 Mar 2008 at 10:19

• Changed state: MoreInfoRequired

[GoogleCodeExporter]

I just realized that your example code uses an anonymous constructor like so:

foo = new function(){
}

Version 2.0.beta2 will offer much better support for this syntax.

Original comment by micmath on 31 Mar 2008 at 10:25

[GoogleCodeExporter]

Excellent!  Your link shows exactly what I would expect.  Great to hear this is
fixed.  My team is looking forward to using meta tags.

I'm also interested to hear more about how "Version 2.0beta2 will offer much 
better
support for [anonymous constructors]".  Perhaps you'll point out these 
improvements
when you announce your release of beta2?  

I can't wait to see beta2 -- you've fixed so many issues for us that it'll feel 
like
beta3.  Thanks for all the swift work.

Original comment by ekaynel...@gmail.com on 2 Apr 2008 at 6:25

[GoogleCodeExporter]

Original comment by micmath on 5 Apr 2008 at 6:00

• Changed state: Fixed

[GoogleCodeExporter]

I just verified your fix on your newly released jsdoc-toolkit v2.0beta2.2.  
Thank you!

Original comment by ekaynel...@gmail.com on 8 Apr 2008 at 6:39