[issue4758] Python 3.x internet documentation needs work
Rafe H. Kettler rafe.kett...@gmail.com added the comment: Thanks Eric, I think you're right. I'll do that. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue4758 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10072] ftplib documentation is unclear
New submission from Rafe H. Kettler rafe.kett...@gmail.com: I think that the documentation for ftplib 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. This can become particularly unclear for less FTP-savvy users. I can propose a patch to the documentation if needed. -- assignee: d...@python components: Documentation messages: 118423 nosy: Rafe.H..Kettler, d...@python, orsenthil priority: normal severity: normal status: open title: ftplib documentation is unclear type: feature request versions: Python 2.7, Python 3.1, Python 3.2 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10072 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue4758] Python 3.x internet documentation needs work
Rafe H. Kettler rafe.kett...@gmail.com added the comment: 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. -- nosy: +Rafe.H..Kettler ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue4758 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9921] os.path.join('x','') behavior
Rafe H. Kettler rafe.kett...@gmail.com added the comment: I think Brian's second solution (the result is simply path2 when path1 is empty or path2 is an absolute path?) is a strong one. If that were tacked on towards the end it would add some clarity to the docs for people who will end up using this behavior or want a more in-depth explanation. At the same time, I think putting it towards the end (as more of a side note, like the bit about behavior on Windows with drive names) lets less sophisticated users (like me) ignore that piece of documentation. -- nosy: +Rafe.H..Kettler ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9921 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9921] os.path.join('x','') behavior
Rafe H. Kettler rafe.kett...@gmail.com added the comment: Radu, while the comments are not as clear for ntpath, the behavior is the same. So, the comment you detailed from posixpath could be adapted to Windows by replacing '/' with 'a separator' or something of that nature. That said, the comment in posixpath could be adapted to clear english like so: join() inserts a separator unless the first part is empty or already ends in a separator. If a part is absolute, join() ignores the previous parts. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9921 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
