The docstrings for `prefixedMethods` and `accumulateMethods` need some polish

[exarkun]

A few issues:

1. prefixedMethods is only documented via a sentence fragment
2. prefixedMethods has no parameter or (clear) return value documentation
3. accumulateMethods duplicates its signature in its docstring
4. accumulateMethods used the deprecated first-person convention
5. accumulateMethods has no parameter documentation

[itamar]

You should probably also document curClass argument is private.

[gehrhorn]

patch file for bug #5909

[gehrhorn]

I improved the documentation for prefiedMethods and accumulateMethods and attached a patch.

[gehrhorn]

I set the status to "fixed", which I don't thing I was supposed to do.

[tom.prince]

This patch deals with points 1, 3 and 4.

The arguments and return value should have explicit documentation (with @param and @return). See the example  here. There are also several examples in the file.

Having added explicit argument and return documentation, the description of the behavior could perhaps be simplified (it seems to me that the wording is more complex than necessary in order to describe the arguments inline), but this is optional.

[exarkun]

Which patch?

[tom.prince]

The attached patch, that was submitted for review.

[exarkun]

(In [36632]) Branching to 'reflect-docs-5909'

[exarkun]

(In [36633]) Apply patch%20%28bug%205909%29.txt

refs #5909

[exarkun]

I applied the patch to the linked branch and made some further doc improvements to it.  Latest twistedchecker build and  latest documentation build.

[tom.prince]

Please commit after fixing points 2+3 (and optionally 1).

1. prefixedMethodNames only refers to a specific class, but addMethodNamesToDict refers to the class and all its base classes, though one is implemented in terms of the other. Also, addMethodNamesToDict looks like an implementation detail (I've filed #6227 to deprecate it).
2. addMethodNamesToDict doesn't return anything.
3. accumulateMethodNames almost always wants to be called as

   methodsDict = {}
   reflect.accumulateMethods(object, methodsDict, '<prefix>_')
   # call methods in methodsDict
   

   But it isn't clear from the documentation that that is how it should be called. An example would be helpful here.

[exarkun]

Thanks. Fixed points 1 and 2 in r36654 and r36655 respectively. I think point 3 is scope creep and I'm inclined not to bother with it for this ticket (these are crappy APIs, anyway, that hardly no one ever cares about or uses).

[exarkun]

(In [36656]) Merge reflect-docs-5909

Author: gehrhorn, exarkun Reviewer: tom.prince Fixes: #5909

Bring the API documentation for some twisted.python.reflect functions up to modern standards.