Docs for BaseHandler.protocol_xxx methods are unclear

[kjohnson]

BPO	4156
Nosy	@birkenfeld

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/birkenfeld'
closed_at = <Date 2009-01-01.11:54:03.206>
created_at = <Date 2008-10-21.11:09:29.503>
labels = ['docs']
title = 'Docs for BaseHandler.protocol_xxx methods are unclear'
updated_at = <Date 2009-01-01.11:54:03.205>
user = 'https://bugs.python.org/kjohnson'

bugs.python.org fields:

activity = <Date 2009-01-01.11:54:03.205>
actor = 'georg.brandl'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2009-01-01.11:54:03.206>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2008-10-21.11:09:29.503>
creator = 'kjohnson'
dependencies = []
files = []
hgrepos = []
issue_num = 4156
keywords = []
message_count = 2.0
messages = ['75023', '78698']
nosy_count = 2.0
nosy_names = ['georg.brandl', 'kjohnson']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue4156'
versions = ['Python 2.6']

[kjohnson]

In the docs for urllib2.BaseHandler previous to Python 2.6, the names of
the protocol_xxx() methods were spelled with 'protocol' in italics to
indicate that it is a placeholder; the actual method name is e.g.
http_opener().
http://www.python.org/doc/2.5.2/lib/base-handler-objects.html

In the Python 2.6 docs this typographic distinction has been lost
http://docs.python.org/library/urllib2.html#basehandler-objects
so it is not so clear that e.g. protocol_open() is not an actual method.

I suggest either restoring the italics or using a spelling such as
<protocol>_open() for the method names. If this is difficult then the
body of the descriptions should be rewritten to make it clear that the
'given protocol' is indicated by the name of the method.

[birkenfeld]

Fixed in r68117.