[Doc-SIG] Documenting "Magic" Methods

[Fred L. Drake, Jr.]

Moshe Zadka writes:
 > I assumed that the Python documentation has a standard way to document
 > classes which define magic methods. However, on looking through the
 > documented modules, I saw that it was elegently (and sometimes not so
 > elegantly) avoided -- "dictionary-like interface" is the only thing (apart
 > from examples) that can be found about
 > shelve.shelve.__[get|set|del]item__.
 > 
 > Is there something I missed, or is this area really untouched?

  You didn't miss anything!
  I'm not sure it makes sense to document the __*__() methods
individually; many of them don't even make that much sense
individually.
  I *think* describing the objects that implement these as
implementing the mapping/numeric/sequence protocols is the right
thing, but there's definately space for debate here.  Did you come
across a reason to document them individually?


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at beopen.com>
BeOpen PythonLabs Team Member