2009/7/13 William Stein <[email protected]>: > > 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/
Yes, I think it should be said that lots of people around scipy realized that good docstrings + lots of example doctests are essential, so things are going in the right direction. > >> >> 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 +1, it's an investment that will pay off in the long run. Ondrej --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
