@example doesn't work for namespaces

[GoogleCodeExporter]

What steps will reproduce the problem?
1. Create an @example for a namespace.

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

- Expect to see @example under the namespace description.

- @example doesn’t render for a namespace.  See the ModifyRowsResults
namespace in the test file for an example.

- Workaround:  Include examples for the fields and methods of a namespace.
 This isn’t a great workaround when you really only want to have one
example that demos usage typical for all methods in a namespace.

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:09

Attachments:

• JsDocToolkitIssueTest.zip
• clientapi_docs.zip

[GoogleCodeExporter]

This is simply down to the template definition and what it outputs.  Add the 
following 3 lines before {+resolveLinks(data.classDesc)+} in 
templates/jsdoc/class.tmpl at around line 64 (in the class summary setion).

<if test="data.example">
    <pre class="code">{+data.example+}</pre>
</if>

Your examples will/should now be generated...

Original comment by darren.t...@googlemail.com on 26 Mar 2008 at 3:40

[GoogleCodeExporter]

I notice that if the object being tagged as @namespace is a function, the 
example
does appear. The problem with namespaces that are object literals is they don't 
have
a "Summary" so there is no place for the example to be shown. I can modify the 
jsdoc
template so that it shows a summary for all namespaces, even object literals.

Original comment by micmath on 26 Mar 2008 at 11:52

• Changed state: Started
• Added labels: Type-Enhancement
• Removed labels: Type-Defect

[GoogleCodeExporter]

Modified: templates/jsdoc/class.tmpl
Committed in: revision 551

Modified template to show summary for all namespaces, even object literals.

Original comment by micmath on 26 Mar 2008 at 11:59

• Changed state: Fixed

[GoogleCodeExporter]

This raises the related issue -- how much of the summary info for a namespace 
should
appear on the Class index?  

Right now, the entire description appears on the class index.  

I would actually expect only the first sentence of the description to appear 
because
I would expect the class index to contain brief summaries only.  Displaying 
just the
first sentence of a namespace's description would parallel the behavior of 
Fields and
Methods, which display only the first sentence of their description in their
"summary" sections.

I could be completely wrong here.  What exists today works fine.

Original comment by ekaynel...@gmail.com on 27 Mar 2008 at 12:30

[GoogleCodeExporter]

Good point. I agree, the index page should only have brief summaries. I'll 
reopen
this issue rather than start a new one.

Original comment by micmath on 27 Mar 2008 at 12:46

• Changed state: Accepted

[GoogleCodeExporter]

Modified:
templates/jsdoc/allfiles.tmpl
templates/jsdoc/index.tmpl

Committed in: revision 552.

Modified indexes to only show summary of descriptions (the first sentence).

Original comment by micmath on 27 Mar 2008 at 12:58

[GoogleCodeExporter]

Original comment by micmath on 27 Mar 2008 at 12:58

• Changed state: Fixed

[GoogleCodeExporter]

Sorry, I didn't realize you'd posted updated versions of the toolkit -- I was 
looking
at the project page instead of the download page.  Glad to see the updates.

I took a look at the two issues covered in this bug:

1)  Verified & looks great:  Class Index summary page.  

The main index page only shows the first sentence of the description for each 
class.
 Perfect!

2)  Not so sure of the fix:  Namespace @examples.  

The goal:  The addition of @examples to class summaries for namespaces.  

The fix seems to have necessitated the addition of both namespace constructor
summaries and namespace constructor details for all namespaces.  This produces
repetitive content, but I might be missing features.  I would not have expected 
that
it would be necessary to add both of the namespace constructor summary/details
sections to add @examples.

Here's what I would have expected:  

- @examples and @see citations output in the <!----class summary---> section, 
the
part of the class (or namespace) page that precedes the summary/details tables.

- no addition of extra summaries/details table entries for namespace 
constructors 

Here is a page where you can see how content is repeated multiple times in the 
page
(in the <!------Class Summary----->, the <!----------Constructor 
Summary-------> and
the <!----Constructor Details -----> sections):

https://www.labkey.org/files/home/Documentation/API%20Reference/LABKEY.Query.Mod
ifyRowsResults.html?

Original comment by ekaynel...@gmail.com on 8 Apr 2008 at 5:27