Update SamToFastq documentation (#1920)

Update SamToFastq documentation to clarify that the tool works properly for both name-sorted and coordinate-sorted inputs with certain caveats.

src/main/java/picard/sam/SamToFastq.java

@@ -59,12 +59,17 @@
 
 /**
  * <p> Extracts read sequences and qualities from the input SAM/BAM file and writes them into
- * the output file in Sanger FASTQ format.  .
+ * the output file in Sanger FASTQ format.
  * See <a href="http://maq.sourceforge.net/fastq.shtml">MAQ FASTQ specification</a> for details.
  * This tool can be used by way of a pipe to run BWA MEM on unmapped BAM (uBAM) files efficiently.
  * <p>In the RC mode (default is True), if the read is aligned and the alignment is to the reverse strand on the genome,
- * the read's sequence from input sam file will be reverse-complemented prior to writing it to FASTQ in order restore correctly
- * the original read sequence as it was generated by the sequencer.
+ * the read's sequence from input SAM file will be reverse-complemented prior to writing it to FASTQ
+ * in order restore correctly the original read sequence as it was generated by the sequencer.
+ * <p>Note: This tool works with both coordinate-sorted and name-sorted inputs. Although mates come with the
+ * same order in both FASTQ files, the behavior is different between coordinate-sorted versus name-sorted BAM files.
+ * Name-sorted BAM files will produce the very same FASTQs generated from the sequencer, whereas coordinate-sorted
+ * BAMs will result in a scrambled FASTQ file where mates match but the reads are not sorted by name.
+ * This may result in slightly different outcomes when used with non-deterministic mappers such as BWA.
  * <br />
  * <h4>Usage example:</h4>
  * <pre>
@@ -81,13 +86,18 @@
 @DocumentedFeature
 public class SamToFastq extends CommandLineProgram {
     static final String USAGE_SUMMARY = "Converts a SAM/BAM/CRAM file to FASTQ.";
-    static final String USAGE_DETAILS = " Extracts read sequences and qualities from the input SAM/BAM/CRAM file and writes them into" +
-            "the output file in Sanger FASTQ format." +
-            "See <a href=\"http://maq.sourceforge.net/fastq.shtml\">MAQ FASTQ specification</a> for details." +
+    static final String USAGE_DETAILS = "Extracts read sequences and qualities from the input SAM/BAM/CRAM file " +
+            "and writes them into the output file in Sanger FASTQ format. " +
+            "See <a href=\"http://maq.sourceforge.net/fastq.shtml\">MAQ FASTQ specification</a> for details. " +
             "This tool can be used by way of a pipe to run BWA MEM on unmapped BAM (uBAM) files efficiently.</p>" +
-            "<p>In the RC mode (default is True), if the read is aligned and the alignment is to the reverse strand on the genome," +
-            "the read's sequence from input sam file will be reverse-complemented prior to writing it to FASTQ in order restore correctly" +
-            "the original read sequence as it was generated by the sequencer.</p>" +
+            "<p>In the RC mode (default is True), if the read is aligned and the alignment is to the reverse strand on the genome, " +
+            "the read's sequence from input SAM file will be reverse-complemented prior to writing it to FASTQ " +
+            "in order restore correctly the original read sequence as it was generated by the sequencer.</p>" +
+            "<p>Note: This tool works with both coordinate-sorted and name-sorted inputs. Although mates come with the " +
+            "same order in both FASTQ files, the behavior is different between coordinate-sorted versus name-sorted BAM files. " +
+            "Name-sorted BAM files will produce the very same FASTQs generated from the sequencer, whereas coordinate-sorted " +
+            "BAMs will result in a scrambled FASTQ file where mates match but the reads are not sorted by name. " +
+            "This may result in slightly different outcomes when used with non-deterministic mappers such as BWA.</p>" +
             "<br />" +
             "<h4>Usage example:</h4>" +
             "<pre>" +