[Doc-SIG] Documenting "Magic" Methods

[Moshe Zadka]

On Fri, 11 Aug 2000, Fred L. Drake, Jr. wrote:

>   I'm not sure it makes sense to document the __*__() methods
> individually; many of them don't even make that much sense
> individually.

Well, certainly __getitem__ makes sense without __setitem__. And,
I think, __[g|s]setitem__ make sense without __delitem__. Other
combinations are perhaps less popular, but certainly exist.

>   I *think* describing the objects that implement these as
> implementing the mapping/numeric/sequence protocols is the right
> thing

Not if they implement some variance on the classic protocol.
Imagine a class which does:

class bar:

	def __init__(self, value):
		self.value = value

class foo:

	def __init__(self):
		self.data = {}

	def __getitem__(self, key):
		return self[key]

	def __setitem__(self, key, value):
		self[key] = bar(value)

How would you document them?

> Did you come
> across a reason to document them individually?

What I've written above is the essence of the problem I'm having with
sketching the documentation for Cookie.py

--
Moshe Zadka <moshez@math.huji.ac.il>
There is no IGLU cabal.
http://advogato.org/person/moshez