Add doctests for minmum/maximum related functions

[Shimuuar]

Doctests assume current semantics as it's implemented in code. For minimum first tie
wins, for maximum last one,
I think most convincing reason to keep this semantics is that maximum/minimum
pair works in exactly same way when equal values could be distinguished:
>>> data F = F Int Char deriving Show
>>> instance Eq F where F i _ == F j _ = i == j
>>> instance Ord F where compare = comparing (\(F i _) -> i)
>>> V.maximum [F 1 'a', F 1 'b']
F 1 'b'
>>> V.minimum [F 1 'a', F 1 'b']
F 1 'a'
As a bonus it matches behavior of list functions

@lehins@Bodigrim what's your opinion on matter?

Fixes#362

P.S. @lehins you may want to pick second commit for 0.12.2.

[lehins]

I don't know about this. Semigroup instances for Max and Min have different behavior:

λ> import Data.Semigroup
λ> import qualified Data.List.NonEmpty as NE
λ> getMax $ sconcat $fmapMax$ (Arg1'a') NE.:| [Arg1'b'::ArgIntChar]
Arg1'a'
λ> getMin $ sconcat $fmapMin$ (Arg1'a') NE.:| [Arg1'b'::ArgIntChar]
Arg1'a'

PS. Thank you. I did cherry pick it.

P.S. @lehins you may want to pick second commit for 0.12.2.

[lehins]

Minor improvement to show that maximum for generic vectors works with other type of vectors:

Suggested change

	-- >>> import qualified Data.Vector as V
	-- >>> V.maximum $ V.fromList [2.0, 1.0]
	-- >>> import qualified Data.Vector.Generic as VG
	-- >>> import qualified Data.Vector as V
	-- >>> VG.maximum $ V.fromList ([2, 1] :: [Integer])
	-- 2
	-- >>> import qualified Data.Vector as VS
	-- >>> VG.maximum $ VS.fromList ([1, 2, 3] :: [Int])
	-- 3

[Shimuuar]

I think it would be better to explain this in top-level documentation of modules. Otherwise some example will show this difference and some won't.

[Shimuuar]

You're right. List functions behave in weird way:

>>>minimum [Arg1'a', Arg1'b']
Arg1'a'>>> minimumBy compare [Arg1'a', Arg1'b']
Arg1'a'>>>maximum [Arg1'a', Arg1'b']
Arg1'a'>>> maximumBy compare [Arg1'a', Arg1'b']
Arg1'b'

master behaves in same way, and 0.12 always returns first element. Maybe reverting changes to maximum in name of reducing breakage is better... But I don't have strong opinion here.

[Shimuuar]

I've added few more one which uses doctests: D.V.Generic.maximum, examples for maximum/minimum which involve Arg and specified uniq behavior (#214)

Wrt maximum/minimum we have following choice:

Don't change code in master.

1. Same behavior as list analogs
2. Breaking change for maximumBy/maxIndexBy
3. It's possible to get either return first or last behavior for both maximum/minimum using Down. But that's a bit of hack

Revert #180

1. No breaking changes
2. All functions work consistently

I'm slightly lean towards keeping things as they're in master

[Shimuuar]

I've reverted #180 as was discussed in #362 and added notice about difference with Data.List.maximumBy. I think PR is finally ready to merge

[lehins]

Looks great!

[lehins]

Suggested change

-- >>> import qualified Data.Vector.Generic as VG

[lehins]

Suggested change

	-- >>> VG.maximum $ VU.fromList [2.0, 1.0]
	-- 2.0

Seems like a copy paste error, right?

[Shimuuar]

Possibly. I don't want to dig through commit to find out, Fixed

[Shimuuar]

I've addressed everything I thing and squashed few commits together

[Bodigrim]

Nice!