Suggested feature: Add "Config" section to the jsdoc template

GoogleCodeExporter commented 8 years ago

What steps will reproduce the problem?  What is the expected output? What
do you see instead?

[feature suggestion, not a bug]

- We use config objects for many APIs (Chart, GridView, WebPart and soon
more), but there’s no config section in the default template.  This seems
like a common pattern (see
http://extjs.com/deploy/dev/docs/#Ext.grid.GridPanel-configs) so perhaps it
might be something to add?  

- Workaround:  We can modify the template ourselves to output a Config
section for our next version.  Thanks for making this possible.

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

Attachments:

GoogleCodeExporter commented 8 years ago

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

Added labels: Type-Enhancement
Removed labels: Type-Defect

GoogleCodeExporter commented 8 years ago

I looked at your cited example. Are the "configs" just properties that are 
listed
separately due to the fact that they switch how the object works?

I use configuration properties myself in the JsDoc Toolkit source code, so I 
see the
usefulness.

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

Changed state: MoreInfoRequired

GoogleCodeExporter commented 8 years ago

Thanks for considering this as an enhancement.  That would be terrific.

You asked:  "Are the "configs" just properties that are listed separately due 
to the
fact that they switch how the object works?"

The config object for a class is the parameter passed to the class's 
constructor to
provide full setup instructions.   Config properties are not properties of the 
class
-- they are properties of the config object. Does that help?

Display of the config object and its properties in jsdocs would ideally follow 
the
example shown in the Ext GridPanel (see the first link below).  

Better links to the examples mentioned earlier:
<a href="http://extjs.com/deploy/dev/docs/?class=Ext.grid.GridPanel">Ext Grid 
Panel</a>
<a
href="https://www.labkey.org/download/clientapi_docs/symbols/LABKEY.Chart.html#c
onstructor">LabKey
Chart</a>
<a 
href="https://www.labkey.org/download/clientapi_docs/symbols/LABKEY.GridView.htm
l#constructor">LabKey
Grid View</a>
<a 
href="https://www.labkey.org/download/clientapi_docs/symbols/LABKEY.WebPart.html
#constructor">LabKey
Web Part</a>

Thanks again for considering this, Michael.

Original comment by ekaynel...@gmail.com on 30 Mar 2008 at 7:28

GoogleCodeExporter commented 8 years ago

Documenting properties of parameters is already supported, described under the
"Parameters With Properties" heading here:

  http://www.jsdoctoolkit.org/wiki/index.php?page=param

These appear in the parameter listing. You are suggesting they appear in a 
separate
section?

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

GoogleCodeExporter commented 8 years ago

Yes, jsdocs certainly provides sufficient functionality to get these properties
documented (as you describe in the "Parameters with Properties" page).  We've 
used
this strategy today successfully, thanks to your terrific tool (see:
https://www.labkey.org/download/clientapi_docs/symbols/LABKEY.Chart.html#constru
ctor ).

The reason to suggest an enhancement here is that the current 
parameter.properties
listings do not provide sufficient prominence and readability for these key 
entities.
 Config properties are actually items that we would usually consider top-level
parameters or fields (and could have implemented as such).   They're just 
bundled
together as Config properties because they are typically defined together for 
each
instance.

We can certainly modify the jsdoc template ourselves to create a section for the
config "properties."  However, I believe we're using a common pattern (as seen 
in the
Ext Grid Panel and other Ext classes), so it would be useful to special-case 
config
"properties" in the tool.

As you can see here:
http://extjs.com/deploy/dev/docs/?class=Ext.grid.GridPanel
the config properties are given greater visibility and readability by being 
called
out as a separate section (at the same level as Fields and Methods) for Grid 
Panel. 
Each config property is top-level within the config section. My team considers 
the
pattern used by Ext Grid Panel to display config as the model for displaying 
config
properties.

So the jsdoc class summary would look like this:

Constructor Summary
    constructor
Config Summary (not sure on the name for this)
    configproperty1
    configproperty2
    configproperty3
Methods Summary
    method1
    method2
Fields Summary
    field1
    field2

This pattern makes sense because each configproperty could easily have been 
defined
as a public Field, so deserves equivalent prominence and structure.  Just like
Fields, config properties are likely to have a lot of info and @examples.

In the Details section, there would then be plenty of room and structure for
@examples for individual configproperties.  You can see how examples get hard 
to read
(and are not called out as @examples) in the config.gridCustomizeCallback 
listing for
LabKey's GridView:
https://www.labkey.org/download/clientapi_docs/symbols/LABKEY.GridView.html

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

GoogleCodeExporter commented 8 years ago

Seattle has had April showers this weekend, so I had a chance to dig into the 
class
template.  Quite fun.  I updated the (attached) class.tmpl file for the March 28
release of the jsdoc-toolkit-v2-beta to provide a minimal implementation of the
config output feature described above.  It's fast-and-dirty, but perhaps a 
reasonable
first draft.

I've temporarily posted an example of the output here:
https://www.labkey.org/files/home/Documentation/API%20Reference/symbols/LABKEY.C
hart.html
(yes, there are stylesheet conflicts in my test area -- please overlook).  A 
zip of
the output is also attached to this post.

What's missing:
- A few tags.  I commented out fields that gave me trouble with the "{# comment 
#}"
syntax.
- Good judgment for putting parameter.properties into the "config" section and
removing them from the constructor section.  This version places all dot 
properties
of constructor parameters into the config section (yuck).

What's needed:
- To place only real config.properties into the config section.
- To get @see working for these properties (I had to comment out the <if> block 
that
would have output @see info).

Original comment by ekaynel...@gmail.com on 6 Apr 2008 at 1:04

Attachments:

GoogleCodeExporter commented 8 years ago

One more link.  The following page displays the output of the unmodified 
template,
for comparison with the changes linked above:
https://www.labkey.org/download/clientapi_docs/symbols/LABKEY.Chart.html

Original comment by ekaynel...@gmail.com on 6 Apr 2008 at 1:22

GoogleCodeExporter commented 8 years ago

I've updated the (attached) class.tmpl file to be smarter about what it 
considers
config properties.

It now only outputs config properties in the "Config Summary" and "Config 
Details"
sections when these properties are defined in the annotations for the 
constructor.
These properties are excluded from the list of "config" parameter properties in 
the
"Constructor Details" section.

This implementation requires you to call your config parameter "config."

Again, this version updates the March 25th release of the jsdoc toolkit v2 beta.

Original comment by ekaynel...@gmail.com on 7 Apr 2008 at 7:10

Attachments:

class.tmpl

GoogleCodeExporter commented 8 years ago

I was delighted to discover that the downloads page a more recent releases than 
those
advertised on the http://code.google.com/p/jsdoc-toolkit/ (project home) page.

I modified the latest version of the class.tmpl file to output config sections. 

The class.tmpl file came from the hot-off-the-presses version of the 
jsdoc-toolkit
2.0.beta2.2 released at about 5pm PST April 7th.

I've attached both the modified class.tmpl file and a zip of the results for 
our site
as a demo.

Original comment by ekaynel...@gmail.com on 8 Apr 2008 at 4:30

Attachments:

GoogleCodeExporter commented 8 years ago

Original comment by micmath on 8 Apr 2008 at 8:14

Changed state: Accepted

vamsikrishnamannem / jsdoc-toolkit

Suggested feature: Add "Config" section to the jsdoc template #109