basinhopping: deal more cleanly with failed minimizations

There was a question on scipy-user mailing list a while back 

http://scipy-user.10969.n7.nabble.com/SciPy-User-determining-success-of-scipy-optimize-basinhopping-td18515.html

which pointed out that the global minimizer optimize.basinhopping() doesn't deal very cleanly with failed minimizations.  Currently it just prints a warning if disp is True.

This pull request modifies basinhopping very slightly so that it now keeps track of how many failed minimizations there were and returns the total in the Result() object as `result.minimization_failures`.

I also added a test to ensure that this was handled correctly.

Also, I took this opportunity to clean up some of the basinhopping comment formatting and add more comments and documentation.