I'll add doctests when @josevalim gives the bat signal to go ahead with the API changes.