Author rafe.kettler
Recipients beazley, eric.araujo, ezio.melotti, georg.brandl, orsenthil, rafe.kettler, yu_jin_zhi
Date 2010-10-11.15:36:33
SpamBayes Score 1.36806e-08
Marked as misclassified No
Message-id <1286811395.2.0.37939241937.issue4758@psf.upfronthosting.co.za>
In-reply-to
Content
I stumbled upon this issue and I feel similarly about the documentation for a particular module, ftplib. I think that the documentation is a bit too concise and assumes that the reader in an expert in the protocol when the point of the module is to abstract out such details.

For example, for the error documentation, the exceptions are only explained by the error code the server can return to trigger them. So, while the explanation of error_perm, for example, should say something about permissions, it just says "raised when an error code in the range 500–599 is received." This is particularly unclear for those with no knowledge of the internals of the protocol.

Also, in the documentation for RetrLines(), the documentation mentions the options LIST, NLST, and MLSD without explaining what they are. I know that when I first started using ftplib I had to experiment with each option to determine what they do, and I think it would be better if this was clear in the docs from the start.

I can propose a patch to the documentation if needed.
History
Date User Action Args
2010-10-11 15:36:35rafe.kettlersetrecipients: + rafe.kettler, georg.brandl, beazley, orsenthil, ezio.melotti, eric.araujo, yu_jin_zhi
2010-10-11 15:36:35rafe.kettlersetmessageid: <1286811395.2.0.37939241937.issue4758@psf.upfronthosting.co.za>
2010-10-11 15:36:34rafe.kettlerlinkissue4758 messages
2010-10-11 15:36:33rafe.kettlercreate