Open GoogleCodeExporter opened 9 years ago
Original comment by micmath
on 30 Mar 2008 at 1:04
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
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
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
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
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:
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
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:
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:
Original comment by micmath
on 8 Apr 2008 at 8:14
Original issue reported on code.google.com by
ekaynel...@gmail.com
on 26 Mar 2008 at 9:40Attachments: