[Python-Dev] Why is documentation not inline? (original) (raw)

Benjamin Peterson benjamin at python.org
Mon May 20 00:33:18 CEST 2013

2013/5/19 Demian Brecht <demianbrecht at gmail.com>:

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 buildopener, 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 buildopener. It seems like external docs is standard throughout the stdlib. Is there an actual reason for this? ernal One is legacy. It certainly wasn't possible with the old LaTeX doc system. Another is that even if you do have API documentation inline, you have to have a lot of juggling in the external file to create the desired narrative structure which may not be the same as the code layout in the file.

-- Regards, Benjamin

More information about the Python-Dev mailing list