This is an attempt at solving several problems reported by novice
users. The old rendering was very compact and quite fine once you
got used to its, ..., "conventions". But it was also sometime rather
hard to read.
First of all, it abused bold and italic. It also "merged" optional
parameters and parameters with default content. It got worst when
the documentation was spread over mutiple lines.
For property types and constructors with large number of parameters,
it was also quite unreadable.
The new representation, while far from perfect, is less dense and
more explicit. It has a separate column for "optional" using the
new "metadata chip" documentation concept. It is also an aligned
table and correctly renders multi-line documentation.
Finally, it adds a "note" message when the named parameter convention
is used. This way the users looking at the examples will be less
confused.
Emmanuel Lepage Vallee