[Guido]
You're lucky that doctest doesn't return dictionaries! For functions that return dictionaries, it's much more natural *for documentation purposes* to write
book() {'Fred': 'mom', 'Ron': 'Snape'}
than the necessary work-around. You may deny that's a problem, but once we've explained dictionaries to our users, we can expect them to understand that if they see instead
book() {'Ron': 'Snape', 'Fred': 'mom'}
they will understand that that's the same thing. Writing it this way is easier to read than
book() == {'Ron': 'Snape', 'Fred': 'mom'} 1
I always have to look twice when I see something like that.
sortdict(book()) {'Fred': 'mom', 'Ron': 'Snape'}
Explicit is better etc. If I have a module that's going to be showing a lot of dict output, I'll write a little "sortdict" function at the top of the docs and explain why it's there. It's clear from c.l.py postings over the years that lots of people *don't* grasp that dicts are "unordered". Introducing a sortdict() function serves a useful pedagogical purpose for them too. More subtle than dicts for most people is examples showing floating-point output. This isn't reliable across platforms (and, e.g., it's no coincidence that most of the .ratio() etc examples in difflib.py are contrived to return values exactly representable in binary floating-point; but simple fractions like 3/4 are also easiest for people to visualize, so that also makes for good examples).
They [difflib.py docstring docs] are also more voluminous than I'd like the docs for difflib to be...
Not me -- there's nothing in them that I as a potential user don't need to know. But then I think the Library docs are too terse in general. Indeed, Fredrick makes part of his living selling a 300-page book supplying desperately needed Library examples <0.5 wink>. WRT difflib.py, it's OK by me if Fred throws out the examples when LaTeXing the module docstring, because a user can still get the info *from* the docstrings. For that matter, he may as well throw out everything except the first line or two of each method description, if you want bare-bones minimal docs for the manual. no-denying-that-examples-take-space-but-what's-painful-to-include- in-the-latex-docs-is-trivial-to-maintain-in-the-code-ly y'rs - tim