Improving plt.hist documentation

[GregoryAshton]

Adds a description of the return value of plot.hist(). Suggested by tcaswell in this SO post. I have tried my best to stick to the numpy doc format but admit I was confused as to if this should go in the return statement or the extended description at the top of the docstring.

[tacaswell]

You should remove these lines.

[pelson]

👍 - I would merge this. @tacaswell?

[tacaswell]

This needs to be 'array or list of arrays', the latter is if you call hist with `hist([data1, data2, ...])

[GregoryAshton]

I had not though of that, as far as I am aware bins should always be a single array of the bin edges.

[tacaswell]

You should also add a note about how the list elements map to the input. While you are working on this documentation could you also update the input docs to state that you can pass in hist([data1, data2...])? The prose says you can, but the Parameters section does not.

[GregoryAshton]

Okay @tacaswell. For the x parameter, it currently has array_like, shape (n, ) . But if hist([data1, data2...]) then the shape will be either:

• (n, m) where n is the number of data sets and m the length of data sets if they are all the same
• (n,) where n is the number of data sets if the data sets are of different lengths.

Is it okay to leave out the shape of the return from the parameters section or is it required? I feel like it will just be more confusing if it is left in.

[tacaswell]

This is the cost of writing 'simple' functions that 'just work'.

I would say something like '(n,) array or sequence of (n,) arrays'