Opened 13 years ago

Closed 10 years ago

#1144 defect closed fixed (fixed)

Documentation: twisted.internet.reactor does not appear in the API docs

Reported by: moof Owned by:
Priority: highest Milestone:
Component: core Keywords: documentation
Cc: Jean-Paul Calderone, spiv, moof, Michael Hudson-Doyle, Thijs Triemstra Branch: branches/twisted.internet.reactor-doc-1144
branch-diff, diff-cov, branch-cov, buildbot
Author: exarkun

Description


Attachments (1)

reactor-doc-1144.patch (759 bytes) - added by collab 10 years ago.
patch against r24237

Download all attachments as: .zip

Change History (24)

comment:1 Changed 13 years ago by moof

Everywhere you look you see the line:

from twisted.internet import reactor

Yet there is no documentation for this module in the API, as it magically
removes itself.

Something you can click on that says:

* The default reactor is SelectReactor - with a link to it
* This alias works for any reactor that is installed, and is installed when the
reactor.install() method is called
* For more information see SelectReactor, the reactor basics page and the
various reactor interfaces (which should be listed in the help text)

comment:2 Changed 13 years ago by Jean-Paul Calderone

Maybe there needs to be some mention of how the reactor works in the
introductory documentation.  Or maybe there is one already and it needs to be
highlighted.  Or maybe something else.

Note that twisted.internet.reactor is fully documented by the IReactor*
interfaces in twisted.internet.interfaces, it just may not be clear to people
new to Twisted.

comment:3 Changed 13 years ago by moof

It's in the HOWTOs, in Choosing a Reactor, and in Reactor basics. But it's not
obvious, you have to do a bit of reading to realise this. 

It is also confusing. You're importing something the API docs say doesn't exist.
It should appear in the api docs, along with explanatory text.

See also issue 1145. This would be an ideal place to put that document, or refer
to it, at the very least.

comment:4 Changed 13 years ago by hypatia

Adding things to the API docs aren't as easy as you might think. Most of the
pre-canned Services for example don't have proper API docs, because they aren't
defined using standard Python class and def declarations.

comment:5 Changed 12 years ago by hypatia

Cc: hypatia removed
Component: conch
Owner: changed from hypatia to edsuom

comment:6 Changed 12 years ago by Jean-Paul Calderone

Component: conchcore

comment:7 Changed 12 years ago by edsuom

Status: newassigned

comment:8 Changed 10 years ago by Jean-Paul Calderone

Cc: Michael Hudson-Doyle added
Owner: changed from edsuom to Jean-Paul Calderone
Status: assignednew

maybe we can do something with TwistedModel or whatever in pydoctor, to put something at twisted.internet.reactor?

comment:9 Changed 10 years ago by Michael Hudson-Doyle

Well yes I guess so. What would you like to see there?

comment:10 in reply to:  3 Changed 10 years ago by collab

Cc: collab added

Replying to mwh:

Well yes I guess so. What would you like to see there?

I think moof made a good suggestion, the text is already there:

Replying to moof:

It's in the HOWTOs, in Choosing a Reactor, and in Reactor basics. But it's not obvious, you have to do a bit of reading to realise this.

So something like:

The reactor is the core of the event loop within Twisted -- the loop which drives applications using Twisted.
The reactor provides basic interfaces to a number of services, including network communications, threading, and event dispatching.

comment:11 Changed 10 years ago by moof

At the very least, either a straight copy of IReactor, or something pointing to it, and a short phrase saying that the default is SelectReactor. If you're feeling generous, a link the the different possible reactors, and maybe the docs telling you how to choose one.

The phrase suggested by collab is not a bad intro, but not enough.

The big problem is that people use twisted.internet.reactor all over the place. New people to twisted, reading twisted code for the first time, or even the docs, will naturally want to look it up. And they'll find nothing. And this is confusing. A nice link to the Right Place will help wonders.

comment:12 in reply to:  11 ; Changed 10 years ago by collab

Owner: changed from Jean-Paul Calderone to collab
Priority: highhighest
Status: newassigned

Replying to moof:

The big problem is that people use twisted.internet.reactor all over the place. New people to twisted, reading twisted code for the first time, or even the docs, will naturally want to look it up. And they'll find nothing. And this is confusing. A nice link to the Right Place will help wonders.

This is a very good point, enough to raise the priority of this docs ticket to the max imo. I'll work on a patch based on moof's suggestions, if someone has a better idea, let's hear it. :)

comment:13 in reply to:  12 Changed 10 years ago by collab

Replying to collab:

... enough to raise the priority of this docs ticket to the max imo.

.. especially when this ticket is > 3 years old! :)

Changed 10 years ago by collab

Attachment: reactor-doc-1144.patch added

patch against r24237

comment:14 Changed 10 years ago by collab

Keywords: review added
Owner: collab deleted
Status: assignednew

Attached a patch that covers most of moof's points, up for review.

comment:15 Changed 10 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: set to Jean-Paul Calderone
Status: newassigned

Good start, and good idea - we don't really need pydoctor development to happen in order to resolve this ticket.

comment:16 Changed 10 years ago by Jean-Paul Calderone

author: exarkun
Branch: branches/twisted.internet.reactor-doc-1144

(In [24250]) Branching to 'twisted.internet.reactor-doc-1144'

comment:17 Changed 10 years ago by Jean-Paul Calderone

(In [24251]) apply somewhat modified reactor-doc-1144.patch

refs #1144

comment:18 Changed 10 years ago by Thijs Triemstra

Cc: Thijs Triemstra added; collab removed

Updating for my nickname

comment:19 Changed 10 years ago by Jean-Paul Calderone

Keywords: review added
Owner: Jean-Paul Calderone deleted
Status: assignednew

comment:20 Changed 10 years ago by Thijs Triemstra

Keywords: review removed
Owner: set to Jean-Paul Calderone

Looks good to me, maybe it would be useful to use:

@see: L{IReactorUDP<twisted.internet.interfaces.IReactorUDP>} 

instead of

@see: L{twisted.internet.interfaces.IReactorUDP} 

for better readability in the generated docs?

comment:21 Changed 10 years ago by Jean-Paul Calderone

(In [24261]) provider shorter names

refs #1144

comment:22 Changed 10 years ago by Jean-Paul Calderone

Resolution: fixed
Status: newclosed

(In [24262]) Merge twisted.internet.reactor-doc-1144

Author: exarkun Reviewer: thijs Fixes: #1144

Add a module docstring to twisted.internet.reactor so that pydoctor has something to pick up and include on the page for that module. The docstring briefly explains the reactor and points to the documentation for a number reactor interfaces.

comment:23 Changed 8 years ago by <automation>

Owner: Jean-Paul Calderone deleted
Note: See TracTickets for help on using tickets.