more explicit (and hopefully) clearer documentation of simper

Hope this helps to avoid confusion like that in
https://stackoverflow.com/questions/52876447/

(cherry picked from commit b2f9a47)

man/simper.Rd

@@ -51,48 +51,51 @@ simper(comm, group, permutations = 0, trace = FALSE,
   \eqn{d_{jk}=\sum_{i=1}^S d_{ijk}}{d[jk] = sum(i=1..S) d[ijk]}. 
 
   The \code{simper} functions performs pairwise comparisons of groups
-  of sampling units and finds the average contributions
-  of each species to the average overall Bray-Curtis dissimilarity.
+  of sampling units and finds the contribution of each species to the
+  average between-group Bray-Curtis dissimilarity.
 
   The function displays most important species for each pair of
   \code{groups}.  These species contribute at least to 70 \% of the
   differences between groups.  The function returns much more
-  extensive results which can be accessed directly from the result
-  object (see section Value). Function \code{summary} transforms the
-  result to a list of data frames. With argument \code{ordered = TRUE}
-  the data frames also include the cumulative contributions and
-  are ordered by species contribution.
+  extensive results (including all species) which can be accessed
+  directly from the result object (see section Value). Function
+  \code{summary} transforms the result to a list of data frames. With
+  argument \code{ordered = TRUE} the data frames also include the
+  cumulative contributions and are ordered by species contribution.
 
   The results of \code{simper} can be very difficult to interpret. The
   method very badly confounds the mean between group differences and
-  within group variation, and seems to single out variable species
-  instead of distinctive species (Warton et al. 2012). Even if you make
-  groups that are copies of each other, the method will single out
-  species with high contribution, but these are not contributions
-  to non-existing between-group differences but to within-group
-  variation in species abundance.
-
+  random noise variation, and seems to single out variable species
+  instead of distinctive species (Warton et al. 2012). Even if you
+  make groups that are copies of each other, the method will single
+  out species with high contribution, but these are not contributions
+  to non-existing between-group differences but to random noise
+  variation in species abundances.
 
 }
 
 \value{
   A list of class \code{"simper"} with following items:
   \item{species}{The species names.}
-  \item{average}{Average contribution to overall dissimilarity.}
-  \item{overall}{The overall between-group dissimilarity.} 
+  \item{average}{Species contribution to average between-group dissimilarity.}
+  \item{overall}{The average between-group dissimilarity. This is the sum of
+    the item \code{average}.}
   \item{sd}{Standard deviation of contribution.} 
   \item{ratio}{Average to sd ratio.}
   \item{ava, avb}{Average abundances per group.}
   \item{ord}{An index vector to order vectors by their contribution or
     order \code{cusum} back to the original data order.}
-  \item{cusum}{Ordered cumulative contribution.}
+  \item{cusum}{Ordered cumulative contribution. These are based on item
+    \code{average}, but they sum up to total 1.}
   \item{p}{Permutation \eqn{p}-value. Probability of getting a larger
     or equal average contribution in random permutation of the group
     factor. These area only available if \code{permutations} were used
     (default: not calculated).}
-
 }
 
+\seealso{Function \code{\link{meandist}} shows the average between-group
+   dissimilarities (as well as the within-group dissimilarities).}
+
 \examples{
 data(dune)
 data(dune.env)