Documentation for the best way to get a reference to a reactor reads as contradictory

[cyli]

 http://twistedmatrix.com/documents/12.2.0/api/twisted.internet.reactor.html

"Regardless of which reactor is installed, importing this module is the correct way to get a reference to it."

"New application code should prefer to pass and accept the reactor as a parameter where it is needed, rather than relying on being able to import this module to get a reference."

These seem to be contradictory statements. When/where it should be imported rather than passed should be clarified.

[teratorn]

I guess it means there should be ONE place where you import the reactor (like a twistd plugin file), and then pass it on everywhere else.

[cyli]

(In [35780]) add examples to the docstring for clarity refs #5951

[cyli]

(In [35781]) less passive voice in reactor docstring refs #5951

[cyli]

http://twistedmatrix.com/trac/browser/branches/clarify_reactor_doscstring_5951/twisted/internet/reactor.py for easier reading

[jerub]

Please add a news file before merging.

Approved :)

[cyli]

pydoctor build suceeded:  http://buildbot.twistedmatrix.com/builders/documentation/builds/2543

[cyli]

(In [35841]) Merge clarify_reactor_doscstring_5951: Elaborate on how to import reactors

Author: cyli Reviewer: jerub Fixes: #5951

Clarify the reactor docstring on how to pass reactors around

[exarkun]

Some problems here:

1. do_something_later and do_something do not follow the naming convention.
2. def do_something_later(*args, reactor=None, **kwargs): is not valid Python syntax.
3. import reactor will typically not import the reactor.
4. do_something_later isn't the way to mark up code in a docstring - C{do_something_later} is.

These are minor, but since there are so many of them it would probably be nice to revert this merge (or else fix them in another ticket today).

[exarkun]

(In [35872]) Revert r35841 - the example is broken and diverges from the coding standard

Reopens: #5951

[wirehead]

This should fix the issues addressed with the reverted change.

[wirehead]

Discussion in person: Default of None needs to go away.

[wirehead]

v2 patch

[tomprince]

(In [37903]) Branching to clarify_reactor_doscstring-5951-2.

[tomprince]

(In [37906]) Apply ticket-5951-2-docs.patch from wirehead.

Refs: #5951

[tom.prince]

1. The paragraph about default reactors should be split into multiple sentences.
2. I'm not sure saying anything about multiple reactors makes sense.
3. "Then the - C{doSomethingLater}": the "-" seems superfluous.
4. "Also, imported the reactor": importing.
5. When discussing reactor-already-imported, mentioning twistd *plugins* might be helpful. I was going to suggest that twistd already ensures that (which is true when using --python).
6. It would be good to reference twisted.internet.task.react.