kwargs description lost

[wkeese]

Although dojodoc format allows methods and classes to have both summaries and descriptions, scalar parameters and properties just have summaries, listed like

// foo: Number
//      There's no summary keyword but this is the summary
foo: 0

(where the above example could be either a foo parameter to a function, or a foo property of a class)

However ,when kwArgs gets inlined (ex: charting/action2d/PlotAction's constructor, third parameter), the parameter or property ends up with both a summary and description:

<parameter name="kwargs" type="Object" usage="optional">
<summary><p>Optional arguments for the action.</p></summary>
<description>
<p>An object with the following properties: </p> <ul> <li><p>duration (Number, optional): <p>The amount of time in milliseconds for an animation to last. Default is 400.</p></p> </li> <li><p>easing</p> </li> </ul>
</description>
</parameter>

The api-viewer is just displaying the summary, losing all that essential info from the descriptoin. I could change it to print both summary and description, but perhaps instead the exporter should shove all the information into the summary?

cc @cjolif

See also wkeese/api-viewer#16.

[wkeese]

Or... did you make it the description intentionally so that the viewer could differentiate between the real summary and the list of properties?

[wkeese]

I decide to enhance the doc viewer to handle description tags on properties and parameters, so closing this ticket.

Note that the description field on properties and parameters is different than the description field on methods and classes in the sense that the former supplements the summary, rather than superceding it. In other words, for scalar properties, both the summary and the description needs to get displayed.