Chris Angelico wrote:
if you let your API docs rot when you make changes that callers need to be aware of, you have failed your callers.
Yes, I find that documentation auto-generated from code is usually a poor substitute for human-written documentation. Dumping your formally-written contracts into the docs makes the reader reverse-engineer them to figure out what the programmer was really trying to say. Which do you find easier to grok at a glance: all(L[i] <= L[i+1] for i in range(len(L) - 1)) or # The list is now sorted -- Greg _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
