Fix use of * in epytext markup

[thijs]

For some reason some of the epytext in the codebase is using asterisks, like:

@param *args: description

but this isn't valid epytext, if you run epydoc on these files it will throw errors like:

+--------------------------------------------------------------------------------------------------------------------------------------------
| File /trunk/twisted/trial/reporter.py, line 399, in twisted.trial.reporter.Reporter._writeln
|   Warning: @param for unknown parameter "*args"

Changing this to the following fixes the error and renders the correct docs (at least with epydoc):

@param args: description

Here's a list of broken epytext which should be fixed:

$ grep -E '@param \*' twisted/ -r --include '*.py'
twisted/enterprise/adbapi.py:        @param *args: positional arguments to be passed to func
twisted/enterprise/adbapi.py:        @param **kw: keyword arguments to be passed to func
twisted/enterprise/adbapi.py:        @param *args: additional positional arguments to be passed
twisted/enterprise/adbapi.py:        @param **kw: keyword arguments to be passed to interaction
twisted/internet/base.py:        @param *args: Positional arguments to pass to C{callable}.
twisted/internet/base.py:        @param **kwargs: Keyword arguments to pass to C{callable}.
twisted/internet/task.py:    @param *args: The positional arguments to pass to C{callable}.
twisted/internet/task.py:    @param **kw: The keyword arguments to pass to C{callable}.
twisted/internet/threads.py:    @param *args: positional arguments to pass to f.
twisted/internet/threads.py:    @param **kwargs: keyword arguments to pass to f.
twisted/internet/threads.py:    @param *args: positional arguments to pass to f.
twisted/internet/threads.py:    @param **kwargs: keyword arguments to pass to f.
twisted/mail/imap4.py:        @param *names: The status names to query.  These may be any number of:
twisted/names/client.py:        @param *args: Positional arguments to be passed to
twisted/python/threadpool.py:        @param *args: positional arguments to be passed to func
twisted/python/threadpool.py:        @param **kw: keyword args to be passed to func
twisted/python/threadpool.py:        @param *args: positional arguments to be passed to func
twisted/python/threadpool.py:        @param **kwargs: keyword arguments to be passed to func
twisted/python/util.py:    @param *args: arguments passed to C{function}
twisted/python/util.py:    @param **kwargs: keyword arguments passed to C{function}
twisted/spread/ui/tkutil.py:    @param **kw: see L{SimpleDialog} class
twisted/test/test_stdio.py:        @param *args: strings which will be passed to the child process on
twisted/test/test_stdio.py:        @param **kw: additional arguments to pass to L{reactor.spawnProcess}.
twisted/trial/reporter.py:        @param *args: The arguments for the format string.
twisted/trial/reporter.py:        @param *args: The arguments for the format string.
twisted/trial/unittest.py:        @param *errorTypes: If unspecifed, flush all errors. Otherwise, only
twisted/web/test/test_httpauth.py:        @param **kw: Keywords and C{str} values which will be treated as field

[thijs]

thijs: so can i fix #3501 or does this require pydoctor changes etc
[18:28] exarkun: thijs: can you enumerate the consequences on the ticket?
[18:28] exarkun: You mentioned one already - epydoc will stop reporting errors for those
[18:28] exarkun: I'm not very interested in that one, because we don't use epydoc to generate the documentation. 
[18:29] thijs: im not sure if pydoctor is able to generate proper docs like this, but i guess it is. its just a little confusing to be using epytext but render the docs with pydoctor.
[18:30] exarkun: mwhudson: hey, what do you think of "@param *args:"?
[18:30] thijs: if we want to stick to epydoc markup then it should be fixed, cause this is incorrect epytext
[18:30] mwhudson: exarkun: you mean, is @param args: better?
[18:30] mwhudson: exarkun: i guess i don't really have an opinion
[18:30] thijs: the actual param name is args, not *args right?
[18:30] exarkun: sure
[18:31] mwhudson: exarkun: i think the epytext author is significantly more particular than me about almost everything 
[18:31] mwhudson: s/text/doc/
[18:32] thijs: if we dont get rid of it people will continue to use this broken epytext
[18:32] mwhudson: thijs: to a certain extent, the question is not "is this valid $format" but "is the resulting documentation useful"
[18:32] thijs: true
[18:32] exarkun: yea
[18:32] thijs: and is it?
[18:32] thijs: i guess it is cause nobody noticed/complained before
[18:32] exarkun: I think the reason I preferred * at some point is that from some perspectives, there isn't actually a parameter with that name.
[18:33] thijs: hm yea
[18:33] mwhudson: i don't think i'd find one noticeably better than the other
[18:33] exarkun: in fact
[18:33] exarkun: it just occurred to me that "@param *: ..." is even better than "@param *args: ..." or "@param args: ...".
[18:34] thijs: cause you cant have 2 of them..?
[18:34] exarkun: (or less obtusely, "@positional: ..." and "@keyword: ...")
[18:34] exarkun: right, and their names are irrelevant.
[18:34] thijs: ok
[18:35] exarkun: but that probably doesn't result in useful documentation without bigger pydoctor changes
[18:35] thijs: marking it as wontfix then