Not your fault, but I see this was wrong : it should surely read "if the number of masked values is not zero" (which is not the same thing ! ).  Also the "result itself will be a masked array" is also wrong -- masking is done pointwise, and the result is *always* masked if the input was (from experiment!).

It therefore seems tru"er" to say, that "the output will be masked wherever all the input points are masked"
 -- but even that now depends on mdtol : Possibly the exact truth about what this does has "gone stale", and that isn't your fault !

What it *actually* does is to calculate the statistic only over the unmasked values --and divide by the **number** of unmasked values.  Others, like MEAN, don't seem to need to state this precisely, but I think they are mostly referencing numpy.ma functions.  Meanwhile COUNT uses ma.sum, but doesn't state that explicitly.

So, **I wonder if this _really_ needs explaining** or if, following the introduction of "mdtol", this statement can simply be removed altogether ??
It certainly seems better to make no statement than to say things which are wrong...

If not, possibly we could put a blanket statement at the top to the effect that :
  1. masked calculations operate only on the non-masked input values at each result point (therefore not the full number of input points in every case)
  2. masking of results depends on the general "mdtol" keyword, as described at http://scitools.org.uk/iris/docs/latest/iris/iris/analysis.html#iris.analysis.Aggregator  (yes the reference is a bit weak : we don't have a proper section describing this, only a "whats-new" entry : http://scitools.org.uk/iris/docs/latest/whatsnew/1.6.html?highlight=mdtol#tolerance).