#3 Allows signatures in non-builtins docstrings

[Robin Dunn]

Attached is a patch for objdoc.py that (in addition to
the __docfilter__ change I gave you earlier) will
always look for a function signature in it's docstring
first regardless of whether it is a builtin or not. If
the regex doesn't match then it will use introspection
just like before.

This allows SWIG generated modules to specify the real
signature in their docstring so epydoc won't just
display the (*args, **kwargs) that is in the Python
methods.

[Robin Dunn]

[Robin Dunn]

Logged In: YES
user_id=53955

The second version of the patch adds the ability to
optionally have types specified in the signature too. (The
mods to SWIG I made can optionally output a simplified
version of the param's C type in the python docstring.)

[Robin Dunn]

with optional types

[alan johnson]

Logged In: YES
user_id=943591

might help documentation this

[Edward Loper]

Logged In: YES
user_id=195958

I just applied a patch which implements basically the same
functionallity. Namely:
* If a docstring begins with a signature line, then that
signature is used, even when an argspec signature is
available.
* Types can optionally be specified. However, I changed
the format to use a ":" marker for types (this is to be
consistant w/ my understanding of how types may one day
be marked in Python itself). E.g.:
f(x: int, y: int) -> float

I did *not* include the __docfilter__ change (since it's
unrelated; and I'm not sure it's the best way to implement
that functionality).