Enhanced docstring for callFromThread

[Cory Dodt]

""" [ ... ] and I'm confused every time I see those functions. It's probably too late to change the name, but might I suggest changing the first sentence of callFromThread's docstring from:

Call a function from within another (i.e. non-reactor) thread.

to:

Cause a function to be executed asynchronously on the reactor thread.

"""

It's pretty silly that I have to create a branch to do this, but okay.

[Cory Dodt]

Reassigning randomly, per Glyph.

[Jean-Paul Calderone]

For future reference, you could just attach a patch to the ticket if you want.

[Cory Dodt]

glyph doesn't want it, let's try dash.

[Glyph]

Reassigning rather than ccing

[Cory Dodt]

BTW branch is docstring-1726.

[Glyph]

I definitely see the problem with the existing text, but "Cause a function to be executed asynchronously on the reactor thread" could also mean "when running on the reactor thread, cause a function to be executed asynchronously (e.g. in a thread).

The .NET platform uses "asynchronously" to mean run in a thread with a callback you can request in your own thread.

Let's come up with another phrasing...

[Cory Dodt]

Glyph suggests this instead of the first two paragraphs:

"""From code running within a non-reactor thread (e.g. one created by callInThread), call this method to cause the given function to be invoked at some point in the future by the reactor on the main I/O thread."""

[Jean-Paul Calderone]

What's up with the win32/maintainer-nodes.txt changes in this branch?

The above docstring is inaccurate, so it shouldn't be used. Dropping "asynchronously" from the docstring currently in svn and replacing "on" with "by" seems fine to me.

[Cory Dodt]

(In [17736]) Resolve bug #1726, edit docstring for callFromThread

Fixes #1726

Author: moonfallen

Reviewer: exarkun

Candy: delicious