twisted
Differentiate between undocumented return and returning `None`
From @mthuurne :
No return type documentation can mean that the return type is undocumented or that the function does not return anything. In the case of annotations, the latter is made explicit by having None as the return type. But for code not using annotations we could check whether there are any return value statements in the function body to tell the difference between an undocumented return type and returning nothing.
Some functions in Twisted explicitly document @return: L{None}, but this shows up in the HTML output as if it is an explicitly returned value. For consistency and elegance, I'd prefer to reserve @return: L{None} for functions that actually have return None in their code, for example because they implement an interface that requires them to return a value.
There are also functions that don't return, because they unconditionally raise an exception or because they never exit. These are pretty rare though. But we could add special formatting for such functions when they are annotated with typing.NoReturn.
