Added caveat to gatkdocs for MAPQ read transformers & cleaned up AB annotation gatkdocs

public/java/src/org/broadinstitute/sting/gatk/filters/ReassignMappingQualityFilter.java

@@ -32,10 +32,23 @@ import org.broadinstitute.sting.commandline.Argument;
  * A read filter (transformer) that sets all reads mapping quality to a given value.
  *
  *  <p>
- *     If a BAM file contains erroneous or missing mapping qualities, this 'filter' will set
- *     all your mapping qualities to a given value. Default being 60.
+ *     If a BAM file contains erroneous or missing mapping qualities (MAPQ), this read transformer will set all your
+ *     mapping qualities to a given value (see arguments list for default value).
  *  </p>
  *
+ * <h3>See also</h3>
+ *
+ * <p>ReassignOneMappingQualityFilter: reassigns a single MAPQ value, as opposed to all those found in the BAM file.</p>
+ *
+ * <h3>Caveats</h3>
+ *
+ * <p>Note that due to the order of operations involved in applying filters, it is possible that other read filters
+ * (determined either at command-line or internally by the tool you are using) will be applied to your data before
+ * this read transformation can be applied. If one of those other filters acts on the read mapping quality (MAPQ),
+ * then you may not obtain the expected results. Unfortunately it is currently not possible to change the order of
+ * operations from command line. To avoid the problem, we recommend applying this filter separately from any other
+ * analysis, using PrintReads.</p>
+ *
  *
  * <h3>Input</h3>
  *  <p>
@@ -50,9 +63,9 @@ import org.broadinstitute.sting.commandline.Argument;
  *
  * <h3>Examples</h3>
  *  <pre>
- *    java
- *      -jar GenomeAnalysisTK.jar
- *      -rf ReassignMappingQuality
+ *  java -jar GenomeAnalysisTK.jar \
+ *      -T PrintReads \
+ *      -rf ReassignMappingQuality \
  *      -DMQ 35
  *  </pre>
  *

public/java/src/org/broadinstitute/sting/gatk/filters/ReassignOneMappingQualityFilter.java

@@ -32,7 +32,7 @@ import org.broadinstitute.sting.commandline.Argument;
  * A read filter (transformer) that changes a given read mapping quality to a different value.
  *
  *  <p>
- *     This 'filter' will change a certain read mapping quality to a different value without affecting reads that
+ *     This read transformer will change a certain read mapping quality to a different value without affecting reads that
  *     have other mapping qualities. This is intended primarily for users of RNA-Seq data handling programs such
  *     as TopHat, which use MAPQ = 255 to designate uniquely aligned reads. According to convention, 255 normally
  *     designates "unknown" quality, and most GATK tools automatically ignore such reads. By reassigning a different
@@ -46,7 +46,6 @@ import org.broadinstitute.sting.commandline.Argument;
  *     that have no assigned mapping qualities.
  *  </p>
  *
- *
  * <h3>Input</h3>
  *  <p>
  *	    BAM file(s)
@@ -60,8 +59,8 @@ import org.broadinstitute.sting.commandline.Argument;
  *
  * <h3>Examples</h3>
  *  <pre>
- *    java
- *      -jar GenomeAnalysisTK.jar
+ *    java -jar GenomeAnalysisTK.jar
+ *      -T PrintReads
  *      -rf ReassignOneMappingQuality
  *      -RMQF 255
  *      -RMQT 60

public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/AlleleBalance.java

@@ -46,7 +46,12 @@ import java.util.Map;
 
 
 /**
- * The allele balance (fraction of ref bases over ref + alt bases) across all biallelic het-called samples
+ * Allele balance across all samples
+ *
+ * <p>The allele balance is the fraction of ref bases over ref + alt bases.</p>
+ *
+ * <h3>Caveats</h3>
+ * <p>Note that this annotation will only work properly for biallelic samples that are called as heterozygous.</p>
  */
 public class AlleleBalance extends InfoFieldAnnotation {
 

public/java/src/org/broadinstitute/sting/gatk/walkers/annotator/AlleleBalanceBySample.java

@@ -51,7 +51,7 @@ import java.util.List;
  * <p>The allele balance is the fraction of ref bases over ref + alt bases.</p>
  *
  * <h3>Caveats</h3>
- * <p>Note that this annotation will only work properly for biallelic het-called samples.</p>
+ * <p>Note that this annotation will only work properly for biallelic samples that are called as heterozygous.</p>
  * <h4>This is an experimental annotation. As such, it is unsupported; we do not make any guarantees that it will work properly, and you use it at your own risk.</h4>
  */
 public class AlleleBalanceBySample extends GenotypeAnnotation implements ExperimentalAnnotation {