Handle overloaded functions

[tristanlatr]

Overload signatures do not currently show up in the output.

The signature attribute of the Function class could simply de transformed to signatures containing a list of ast expressions.

[mthuurne]

Having signatures as a list sounds like a good idea.

Should we support per-signature docstrings?

We have the following overloaded function in pydoctor/epydoc/markup/epytext.py:

@overload
def parse(text: str) -> Element: ...

@overload
def parse(text: str, errors: List[ParseError]) -> Optional[Element]: ...

def parse(text: str, errors: Optional[List[ParseError]] = None) -> Optional[Element]:
    """
    Return a DOM tree encoding the contents of an epytext string.  Any
    errors generated during parsing will be stored in C{errors}.

    @param text: The epytext string to parse.
    @param errors: A list where any errors generated during parsing
        will be stored.  If no list is specified, then fatal errors
        will generate exceptions, and non-fatal errors will be
        ignored.
    @return: a DOM tree encoding the contents of an epytext string,
        or C{None} if fatal errors were encountered and an C{errors}
        accumulator was provided.
    @raise ParseError: If C{errors} is C{None} and an error is
        encountered while parsing.
    """
    # (implementation)

Note that the @return clause is different from the version in Git; I'll submit a PR to fix the current docstring.

This docstring is complicated by the fact that each of the overloaded variants has a slightly different behavior. Perhaps it would be clearer if they could be documented separately:

@overload
def parse(text: str) -> Element: ...
    """
    Return a DOM tree encoding the contents of an epytext string.

    @param text: The epytext string to parse.
    @return: a DOM tree encoding the contents of an epytext string.
    @raise ParseError: If a fatal error is encountered while parsing.
        Non-fatal errors are ignored.
    """"

@overload
def parse(text: str, errors: List[ParseError]) -> Optional[Element]: ...
    """
    Return a DOM tree encoding the contents of an epytext string.  Any
    errors generated during parsing will be stored in C{errors}.

    @param text: The epytext string to parse.
    @param errors: A list where any errors (fatal and non-fatal) generated
        during parsing will be stored.
    @return: a DOM tree encoding the contents of an epytext string,
        or C{None} if fatal errors were encountered.
    """

def parse(text: str, errors: Optional[List[ParseError]] = None) -> Optional[Element]:
    # (implementation)

It would be best to handle this in separate PRs though: multiple signatures is something we can integrate and benefit from before we might add support for per-variant docstrings. But knowing that we may want to have per-variant docstrings later could guide the way we render multiple signatures.

[tristanlatr]

Looks like this for now.

I've added some code to pick up the annotations into the Signature object as well, so we generate the annotations in the function header. I'de say it's a bit of a redundancy, for sure, but for long and complex functions it might be worth it.

Let's note that the values are not currently linked to the appropriate URLs but it will be fixed once #402 is merged since it adds some colourizing features to the _ValueFormatter.