Improve docstring of Axes.pcolorfast

[timhoffm]

PR Summary

As part of #10148: Docstring update for Axes.pcolorfast.

@efiring since you seem to be the original author, can you tell me something about the current state. Is the experimental statement still true? If so, is that because of the limitations mentioned in the current docs? Are there any known bugs? Are there any plans to make it a full method? Or is this maybe a dead end? Are users supposed to use this instead of pcolor() or pcolormesh() for the cases that are currently supported? Thanks a lot.

[jklymak]

PEP8 is mad about the length of this line...

[efiring]

pcolorfast has been there for a long time now, and I haven't seen a clamor to remove it. It's an odd method in that it can return any of 3 different objects; but it serves a definite purpose. I believe the contents of the present docstring correctly describe how it works. I would not object to removing the "Experimental" part, but at the same time, there are some things that should be fixed--especially the lack of support for log scales when the intermediate-speed option is invoked. I suspect this would not be terribly hard for someone who understands how the normal image and pcolormesh handle scales, but it's all pretty complicated to try to figure out. Once it is understood, it is probably a matter of adding only a few lines of code to image.PcolorImage.

Also, I think that the 3 objects returned by pcolorfast could be made more similar than they are now.

(Quadmesh (and pcolormesh) desperately needs some refactoring and reworking also.)

[timhoffm]

Thanks @efiring

For now, I'd just leave the "Experimental" part. I think it's can be rather confusing to have methods methods (imshow, pcolor, pcolormesh and pcolorfast) that do very similar things. The latter being sort of smart to choose between the others. That should really be explained to the user and it would make sense to try and unify this further as @efiring mentioned. So let's not stabilize the current API further by removing the "Experimental" statement. - At least not as part of this docstring cleanup. That should be a separate and well-thought PR.

[timhoffm]

@meeseeksdev backport to v2.2.x