Display types in function signatures

[not-my-profile]

Something that really bothers me about Pydoctor is that the return type is only shown at the very end of the function documentation:

Another problem is that parameter default values can be far apart from the type & description of parameters.

I think the best way to solve both of these problems would be to display all types in the function signature. I'd argue that types are important enough to warrant them being displayed first. And actually when I want to learn about a function I want to read its full type signature first before reading any text about the function.

This would obviously require a rework of the functionDef as has already been suggested in #422. Though I don't think <wbr> are the way to go. If the signature is too long it should just be properly formatted from the get go.

[tristanlatr]

See #417 (comment) about type annotations in signatures.

I think it’s a good idea to show them I the signature.

[tristanlatr]

Let's talk about rendering the type annotation inside signatures, @cretz, here is what's my old code (#417) currently generates for a random function (not overloaded):

As talked about with @glyph, I believe we should only see the following instead:

Here are notes on this issue:

Change the FieldHandler to show nothing when none of the parameters (annotated or not) are documented (stop listing the parameters or return value as "undocumented" when they only have AST annotation, this makes the behaviour more consistent because we don't list undocumented param that don't have AST annotation). In case there is only one parameter documented, then still show the whole table of parameters with "undocumented" when parameters miss docs, like we do for functions without annotations.