Merge pull request #318 from broadinstitute/dr_improve_dcov_documentation

Improve -dcov documentation to address recent user confusion

public/java/src/org/broadinstitute/sting/gatk/arguments/GATKArgumentCollection.java

@@ -128,10 +128,12 @@ public class GATKArgumentCollection {
     @Argument(fullName = "downsample_to_coverage", shortName = "dcov",
               doc = "Coverage [integer] to downsample to. For locus-based traversals (eg., LocusWalkers and ActiveRegionWalkers)," +
                     "this controls the maximum depth of coverage at each locus. For non-locus-based traversals (eg., ReadWalkers), " +
-                    "this controls the maximum number of reads sharing the same alignment start position. Note that the " +
-                    "coverage target is an approximate goal that is not guaranteed to be met exactly: the GATK's approach " +
-                    "to downsampling is based on even representation of reads from all alignment start positions, and the " +
-                    "downsampling algorithm will under some circumstances retain slightly more coverage than requested.",
+                    "this controls the maximum number of reads sharing the same alignment start position. Note that this downsampling " +
+                    "option does NOT produce an unbiased random sampling from all available reads at each locus: instead, the primary goal of " +
+                    "the to-coverage downsampler is to maintain an even representation of reads from all alignment start positions " +
+                    "when removing excess coverage. For a true across-the-board unbiased random sampling of reads, use -dfrac instead. " +
+                    "Also note that the coverage target is an approximate goal that is not guaranteed to be met exactly: the downsampling " +
+                    "algorithm will under some circumstances retain slightly more coverage than requested.",
               required = false)
     public Integer downsampleCoverage = null;