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. 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. > 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 --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
