Document that Response.iter_lines is broken and should be avoided

[bemoody]

The Response.iter_lines method is seriously broken (it inserts fake blank lines in unpredictable places.)

The earliest report of this I've found is pull #2431 (January 2015).

The behavior was apparently fixed in the 3.0.0 branch, by pulls #3923 and #3984. (I think #3923 fixes the delimiter!=None case and #3984 fixes the delimiter=None case. But I haven't tested it.)

The problem was raised again in issues #3980, #4121, and #5540.

Pull #4629 attempted to partially fix the issue in the master branch, and was rejected.

Personally, I am skeptical that there is any benefit in preserving this broken behavior. But folks who know better than I do have said that it needs to be maintained.

As long as this isn't fixed, people using the library should be informed that method is broken and they shouldn't use it.