Parameter type information visually hard to find

[DanielSank]

Consider the documentation found at (screenshot below) https://twistedmatrix.com/documents/current/api/twisted._threads.IWorker.html

At present, the type information is set off

• By the string "type"
• At the end of the parameter description
• In parentheses

Parameter types are essential information. Consider

• Putting the type a the beginning of the parameter description
• Omitted the unnecessary word "type"
• Giving the parameters their own colored box

[mthuurne]

I agree that having the type in parentheses at the end is not great. I'm considering to either put the type immediately after the name, similar to PEP 484 annotations (task: Callable), or put it in a separate column.

Types can get quite long, for example the full PEP 484 syntax would be task: Callable[[], None] (a 0-argument callable that returns nothing). Type information becomes even longer when non-builtin types are used as type arguments, for example a list of workers would be List[twisted._threads.IWorker]. Therefore it might be better to have the documentation body on a separate line, below the name + type. It would then look like a definition list rather than a table.

[tristanlatr]

I think the parameters types should be right after the param name, in the same "column", like https://geopy.readthedocs.io/en/stable/#nominatim

[tristanlatr]

Therefore it might be better to have the documentation body on a separate line, below the name + type. It would then look like a definition list rather than a table.

This is not exactly what I did, I stuck with the common way to show arguments types: In parenthesis on the same column as the arg name.
I fix the size of the argument name column to 25%.
To handle the longer type names, I've add potential line breaks after [ or , in type rendering:

[tristanlatr]

after second try, it looks like this (on a small screen):

[mthuurne]

I think that latest version is a big improvement over the current implementation.

The font baseline isn't aligned at the moment: the type names are a few pixels lower than the parameter names. There is probably something that could be done in CSS to fix that.

If the type cell is inside a flex layout (I think I read that in a commit title), maybe enable wrapping? That way, instead of

fields: Sequence[
        Field]

we would have

fields:
Sequence[Field]

[tristanlatr]

Yep I did do that after: only for screens smaller than 650px ,
Please see the changes here: https://pydoctor--299.org.readthedocs.build/en/299/api/pydoctor.epydoc2stan.html

I'll merge the master and mark the PR as ready in a few