[Python-Dev] Why is documentation not inline?

Demian Brecht demianbrecht at gmail.com
Mon May 20 00:29:37 CEST 2013

This is more out of curiosity than to spark change (although I
wouldn't argue against it): Does anyone know why it was decided to
document external to source files rather than inline?

When rapidly digging through source, it would be much more helpful to
see parameter docs than to either have to find source lines (that can
easily be missed) to figure out the intention. Case in point, I've
been digging through cookiejar.py and request.py to figure out their
interactions. When reading through build_opener, it took me a few
minutes to figure out that each element of *handlers can be either an
instance /or/ a class definition (I was looking at how to define a
custom cookiejar for an HTTPCookieProcessor). Yes, I'm (now) aware
that there's some documentation at the top of request.py, but it would
have been helpful to have it right in the definition of build_opener.

It seems like external docs is standard throughout the stdlib. Is
there an actual reason for this?


Demian Brecht

More information about the Python-Dev mailing list