2009/7/13 Minh Nguyen <[email protected]>: > > On Tue, Jul 14, 2009 at 4:16 AM, Ondrej Certik<[email protected]> wrote: > > <SNIP> > >> What I hate about PIL is the lack of docstrings with example doctests. >> But honestly, I hate this about Python standard library too! >> >> Things like this: >> >> In [1]: a = "s" >> >> In [4]: a.format? >> Type: builtin_function_or_method >> Base Class: <type 'builtin_function_or_method'> >> String Form: <built-in method format of str object at 0x7f25b1ba7a80> >> Namespace: Interactive >> Docstring: >> S.format(*args, **kwargs) -> unicode >> >> The docstring is utterly useless. > > Can I get an amen to that? :-) > > Seriously, when I first started learning Python and using the Python > scientific stack (SciPy, NumPy, etc.), such things caused me a lot of > trouble. After reading the associated documentation and the source > code, I would still be no more enlightened than before doing so. Yes, > having examples and lots of them are really helpful. It's a simple way > of helping users get started on using one's library/code. >> I just got used to having thorough docstrings + doctests and imho Sage >> raised a bar here and hopefully other will follow too.
I very strongly agree. I complained about this very loudly on the scipy list about two years ago. This resulted in a lot of improvement. See, e.g., http://www.scipy.org/PyLab where it says: "In a posting to the SAGE developer list, the lead SAGE developer, William Stein, described how he wishes NumPy and SciPy would follow more consistent documentation standards. Shortly thereafter Travis Oliphant committed the documentation standard which should be used in NumPy and SciPy." Stefan van der Walt and many others in the numpy/scipy community have put in tremendous effort to improve the scipy/numpy docs. Here are the slides from one nice talk Stefan gave on this: http://mentat.za.net/numpy/numpy_doc_marathon2008/ > > Without examples of usage, it's like the code or library has been > written for programmers only. There have been many times where my > friends and colleagues have complained to me that software x is > *written* for programmers. And then I would spend about an hour or two > helping them figuring out how to use software x. +1. I think everybody benefits greatly when they type "foo?" and get lots of examples that (1) work, (2) they can just paste in and try, that (3) really illustrate all the inputs to foo. I think the mathematica documentation does this pretty well, but in many cases I think Sage goes even further, and I'm starting to get very proud of how many good examples we have in the Sage docs. Right now with sage-4.1: sage -coverageall ... Overall weighted coverage score: 77.8% Total number of functions: 22398 We need 495 more function to get to 80% coverage. We need 1615 more function to get to 85% coverage. We need 2735 more function to get to 90% coverage. Let's push for the magic 80% ! William > > >> And a lack of >> online documentation too, where sphinx raised a bar. PIL has this: >> >> http://www.pythonware.com/library/pil/handbook/index.htm >> >> which is not bad, but sphinx is better. > > Yeah... someone once said that documentation is like sex. When it's > good, it's really good. When it's bad, it's better than nothing :-) > > -- > Regards > Minh Van Nguyen > > > > -- William Stein Associate Professor of Mathematics University of Washington http://wstein.org --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/sage-devel URLs: http://www.sagemath.org -~----------~----~----~----~------~----~------~--~---
