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.
It no longer does `foo(bar[,bar=42])` and will rather do `(foo, bar)`.
This is easier to read and some new user are no familiar with the
optional parameter convention. They copy/paste the mangled value in
their config and end up with invalid Lua.
Below a screen width of 768px (Bootstrap's "medium" breakpoint)
the sidebar will collapse to a small strip. Hovering the sidebar will
fully reveal it until the mouse leaves it.
Clicking the sidebar will reveal it until another part of the page is
clicked.
* Rendering problems
* Incomplete type information
* Obsolete type information
* Missing type information
* Missing return value
* Incomplete return value type
It is hard know to which row a "chip" like inherited belongs to. This
fixes it for mouse users.
I also tried using alternate row colors, but our colors are so "light"
that there wasn't any good candidate between "white" and the <body>
background color.
This removes the hardcoded foreground color and inherit it from
the browser and/or CSS stylesheet.
This commit only support the foreground colors, future changes could
extend it to support all standard colors.
Some code in awesome concatenate color strings. This means it blows
up when the pattern are used instead of color, with this, it fails
gracefully (by returning the unmodified pattern).
Some widgets like the tasklist serialize the theme colors to use them
in Pango markup. If the theme color were already converted to pattern,
that blew up. With this fix, pattern can be converted back into strings
correctly.
Previously, it was monkey-patching the input layout object. This will
allow to replace the laoyut at runtime. For example, switching from
`fixed.horizontal` to a grid when the number of client gets too large.
It was previously monkey-patching the input layout object into
the final tasklist.
This is a breaking change, but affects undocumented behaviors. By
doing this, it becomes possible to expose the properties in the
public API. This, in turn, allows to document them. Right now,
the documentation is very vague on some behaviors.
As pointed out by @sclu1034, some users might actually pass the return
values of a function with multiple returns. This would cause some
confusing behavior. Documenting previous mistakes is in this case better
than hiding them.
Emmanuel Lepage Vallee
Grzegorz Bednarski
Aire-One
Lucas Schwiderski
Kamack38