Final tweaks to the method docs

src/main/java/org/broadinstitute/hellbender/engine/AbstractConcordanceWalker.java

@@ -116,6 +116,15 @@ protected final void onStartup() {
     // the primary work of the walker.  Must be overridden in implementing classes.
     protected abstract void apply(final TruthVersusEval truthVersusEval, final ReadsContext readsContext, final ReferenceContext refContext);
 
+    /**
+     * {@inheritDoc}
+     *
+     * Implementation of concordance traversal.
+     *
+     * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the
+     * engine package.
+     */
     @Override
     public void traverse() {
         // Process each variant in the input stream.

src/main/java/org/broadinstitute/hellbender/engine/AssemblyRegionWalker.java

@@ -255,12 +255,11 @@ protected ReadsDownsampler createDownsampler() {
     /**
      * {@inheritDoc}
      *
-     * Subclasses can override to provide their own behavior but default implementation should be suitable for most uses.
-     *
+     * Implementation of assembly region traversal.
+     * 
      * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
-     * engine package that extends this class.
-     *
-     * It is not meant to be overridden by tools outside of the engine package.
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the
+     * engine package.
      */
     @Override
     public void traverse() {

src/main/java/org/broadinstitute/hellbender/engine/FeatureWalker.java

@@ -74,13 +74,13 @@ private void initializeDrivingFeatures() {
     protected abstract boolean isAcceptableFeatureType(Class<? extends Feature> featureType);
 
     /**
+     * {@inheritDoc}
+     *
      * Implementation of Feature-based traversal.
-     * Subclasses can override to provide their own behavior but default implementation should be suitable for most uses.
      *
      * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
-     * engine package that extends this class.
-     *
-     * It is not meant to be overridden by tools outside of the engine package.
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the engine
+     * package.
      */
     @Override
     public void traverse() {

src/main/java/org/broadinstitute/hellbender/engine/GATKTool.java

@@ -9,7 +9,6 @@
 import htsjdk.variant.variantcontext.writer.Options;
 import htsjdk.variant.variantcontext.writer.VariantContextWriter;
 import htsjdk.variant.vcf.VCFHeaderLine;
-import htsjdk.variant.vcf.VCFSimpleHeaderLine;
 import java.io.File;
 import java.nio.file.Path;
 import java.time.ZonedDateTime;
@@ -44,12 +43,6 @@
 import org.broadinstitute.hellbender.utils.reference.ReferenceUtils;
 import org.broadinstitute.hellbender.utils.variant.GATKVariantContextUtils;
 
-import java.io.File;
-import java.nio.file.Path;
-import java.time.ZonedDateTime;
-import java.util.*;
-import java.util.stream.Stream;
-
 /**
  * Base class for all GATK tools. Tool authors that wish to write a "GATK" tool but not use one of
  * the pre-packaged Walker traversals should feel free to extend this class directly. All other

src/main/java/org/broadinstitute/hellbender/engine/IntervalWalker.java

@@ -56,12 +56,11 @@ protected final void onStartup() {
     /**
      * {@inheritDoc}
      *
-     * Subclasses can override to provide their own behavior but default implementation should be suitable for most uses.
+     * Implementation of interval-based traversal.
      *
      * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
-     * engine package that extends this class.
-     *
-     * It is not meant to be overridden by tools outside of the engine package.
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the
+     * engine package.
      */
     @Override
     public void traverse() {

src/main/java/org/broadinstitute/hellbender/engine/LocusWalker.java

@@ -142,16 +142,15 @@ protected final void onStartup() {
     /**
      * {@inheritDoc}
      *
+     * Implementation of locus-based traversal.
+     *
      * The default implementation iterates over all positions in the reference covered by reads (filtered and transformed)
      * for all samples in the read groups, using the downsampling method provided by {@link #getDownsamplingInfo()}
      * and including deletions only if {@link #includeDeletions()} returns {@code true}.
      *
-     * Subclasses can override to provide their own behavior but default implementation should be suitable for most uses.
-     *
      * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
-     * engine package that extends this class.
-     *
-     * It is not meant to be overridden by tools outside of the engine package.
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the engine
+     * package.
      */
     @Override
     public void traverse() {

src/main/java/org/broadinstitute/hellbender/engine/MultiVariantWalker.java

@@ -100,6 +100,15 @@ public final VCFHeader getHeaderForVariants() {
         return drivingVariants.getHeader();
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * Implementation of multi-variant traversal.
+     *
+     * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the
+     * engine package.
+     */
     @Override
     public void traverse() {
         final CountingReadFilter readFilter = makeReadFilter();

src/main/java/org/broadinstitute/hellbender/engine/MultiVariantWalkerGroupedOnStart.java

@@ -107,6 +107,15 @@ final static ReferenceContext getExpandedReferenceContext(List<VariantContext> c
         return currentReferenceContext;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * Implementation of multi-variant grouped on start traversal.
+     *
+     * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the
+     * engine package.
+     */
     @Override
     public void traverse() {
         beforeTraverse();

src/main/java/org/broadinstitute/hellbender/engine/MultiplePassVariantWalker.java

@@ -20,7 +20,14 @@ public abstract class MultiplePassVariantWalker extends VariantWalker {
     /**
      * {@inheritDoc}
      *
-     * Overrides the default, single-pass traversal framework of {@link VariantWalkerBase} allowing for multiple passes.
+     * Implementation of multiple-pass variant traversal.
+     *
+     * Overrides the default, single-pass traversal framework of {@link VariantWalkerBase} allowing for multiple
+     * passes.
+     *
+     * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the
+     * engine package.
      */
     @Override
     public void traverse(){

src/main/java/org/broadinstitute/hellbender/engine/ReadWalker.java

@@ -72,18 +72,18 @@ void initializeFeatures() {
     }
 
     /**
-     * Implementation of read-based traversal.
-     * Subclasses can override to provide their own behavior but default implementation should be suitable for most uses.
-     *
-     * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
-     * engine package that extends this class.
+     * {@inheritDoc}
      *
-     * It is not meant to be overridden by tools outside of the engine package.
+     * Implementation of read-based traversal.
      *
      * The default implementation creates filters using {@link #makeReadFilter} and transformers using
      * {@link #makePreReadFilterTransformer()} {@link #makePostReadFilterTransformer()} and then iterates over all reads, applies
      * the pre-filter transformer, the filter, then the post-filter transformer and hands the resulting reads to the {@link #apply}
      * function of the walker (along with additional contextual information, if present, such as reference bases).
+     *
+     * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the engine
+     * package.
      */
     @Override
     public void traverse() {

src/main/java/org/broadinstitute/hellbender/engine/ReferenceWalker.java

@@ -37,13 +37,13 @@ protected final void onStartup() {
     }
 
     /**
+     * {@inheritDoc}
+     *
      * Implementation of reference-locus-based traversal.
-     * Subclasses can override to provide their own behavior but default implementation should be suitable for most uses.
      *
      * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
-     * engine package that extends this class.
-     *
-     * It is not meant to be overridden by tools outside of the engine package.
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the engine
+     * package.
      */
     @Override
     public void traverse() {

src/main/java/org/broadinstitute/hellbender/engine/TwoPassReadWalker.java

@@ -33,6 +33,16 @@
  */
 public abstract class TwoPassReadWalker extends ReadWalker {
 
+
+    /**
+     * {@inheritDoc}
+     *
+     * Implementation of two-pass read-based traversal.
+     *
+     * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the engine
+     * package.
+     */
     @Override
     public void traverse() {
         // Process each read in the input stream.

src/main/java/org/broadinstitute/hellbender/engine/VariantLocusWalker.java

@@ -113,8 +113,13 @@ public boolean requiresReference() {
     }
 
     /**
-     * Implementation of variant-based traversal.
-     * Subclasses can override to provide their own behavior but default implementation should be suitable for most uses.
+     * {@inheritDoc}
+     *
+     * Implementation of variant-locus traversal.
+     *
+     * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the engine
+     * package.
      */
     @Override
     public void traverse() {

src/main/java/org/broadinstitute/hellbender/engine/VariantWalker.java

@@ -88,13 +88,13 @@ public final VCFHeader getHeaderForVariants() {
     }
 
     /**
+     * {@inheritDoc}
+     *
      * Implementation of variant-based traversal.
-     * Subclasses can override to provide their own behavior but default implementation should be suitable for most uses.
      *
      * NOTE: You should only override {@link #traverse()} if you are writing a new walker base class in the
-     * engine package that extends this class.
-     *
-     * It is not meant to be overridden by tools outside of the engine package.
+     * engine package that extends this class. It is not meant to be overridden by tools outside of the engine
+     * package.
      */
     @Override
     public void traverse() {

src/main/java/org/broadinstitute/hellbender/engine/WalkerBase.java

@@ -5,15 +5,14 @@
 
 /**
  * Base class for pre-packaged walker traversals in the GATK engine.
+ *
  * Classes such as {@link ReadWalker} and {@link VariantWalker} in the engine package that implement a standardized traversal should
  * extend this class rather than {@link GATKTool}. Actual concrete tool classes should extend one of the specific walker base
  * types (such as {@link ReadWalker}) or {@link GATKTool} directly rather than this class.
  *
  * Classes that extend {@link WalkerBase} will be unable to directly access engine data sources unless they are in the
- * engine package.
- *
- * This is to allow walker base classes such as {@link ReadWalker} direct datasource access while disallowing it for
- * concrete walker tool implementations, which should get their data via {@link ReadWalker#apply(GATKRead, ReferenceContext, FeatureContext)}.
+ * engine package. This is to allow walker base classes such as {@link ReadWalker} direct datasource access while disallowing
+ * it for concrete walker tool implementations, which should get their data via their {@code apply()} method.
  */
 public abstract class WalkerBase extends GATKTool {
 
@@ -30,14 +29,15 @@ public abstract class WalkerBase extends GATKTool {
      */
     @Override
     final protected ReferenceDataSource directlyAccessEngineReferenceDataSource() {
-        throw new GATKException("Should never access ReferenceDataSource in child classes of Walker.");
+        throw new GATKException("Should never directly access the engine ReferenceDataSource in walker tool classes " +
+                "outside of the engine package. Walker tools should get their data via apply() instead.");
     }
 
     /**
      * {@inheritDoc}
      *
      * Walker tools outside of the engine package should not directly access the engine reads datasource.
-     * They should get their reference data via {@code apply()} instead. Tools that need direct datasource access
+     * They should get their reads data via {@code apply()} instead. Tools that need direct datasource access
      * (e.g., to implement custom traversal patterns) should extend {@link GATKTool} directly rather than a walker class,
      * or introduce a new walker base class for the new traversal.
      *
@@ -46,14 +46,15 @@ final protected ReferenceDataSource directlyAccessEngineReferenceDataSource() {
      */
     @Override
     final protected ReadsDataSource directlyAccessEngineReadsDataSource() {
-        throw new GATKException("Should never access ReadsDataSource in child classes of Walker.");
+        throw new GATKException("Should never directly access the engine ReadsDataSource in walker tool classes " +
+                "outside of the engine package. Walker tools should get their data via apply() instead.");
     }
 
     /**
      * {@inheritDoc}
      *
      * Walker tools outside of the engine package should not directly access the engine feature manager.
-     * They should get their reference data via {@code apply()} instead. Tools that need direct datasource access
+     * They should get their feature data via {@code apply()} instead. Tools that need direct datasource access
      * (e.g., to implement custom traversal patterns) should extend {@link GATKTool} directly rather than a walker class,
      * or introduce a new walker base class for the new traversal.
      *
@@ -62,6 +63,7 @@ final protected ReadsDataSource directlyAccessEngineReadsDataSource() {
      */
     @Override
     final protected FeatureManager directlyAccessEngineFeatureManager() {
-        throw new GATKException("Should never access FeatureManager in child classes of Walker.");
+        throw new GATKException("Should never directly access the engine FeatureManager in walker tool classes " +
+                "outside of the engine package. Walker tools should get their data via apply() instead.");
     }
 }