annotating deprecated methods with @Deprecated (#698)

some methods that were documented as deprecated were not also annotated with @Deprecated
annotating them as deprecated allows tools to warn when these methods are accidentally used

also updating documentation of deprecated methods to point to the replacement method with a valid {@link}

src/main/java/htsjdk/samtools/AbstractBAMFileIndex.java

@@ -387,8 +387,9 @@ protected BitSet regionToBins(final int startPos, final int endPos) {
     }
 
     /**
-     * @deprecated Invoke htsjdk.samtools.Chunk#optimizeChunkList(java.util.List<htsjdk.samtools.Chunk>, long) directly.
+     * @deprecated Invoke {@link Chunk#optimizeChunkList} directly.
      */
+    @Deprecated
     protected List<Chunk> optimizeChunkList(final List<Chunk> chunks, final long minimumOffset) {
         return Chunk.optimizeChunkList(chunks, minimumOffset);
     }

src/main/java/htsjdk/samtools/AbstractSAMHeaderRecord.java

@@ -50,8 +50,9 @@ public String getAttribute(final String key) {
      * Otherwise, the value will be converted to a String with toString.
      * @param key attribute name
      * @param value attribute value
-     * @deprecated Use the version that takes a String value instead
+     * @deprecated Use {@link #setAttribute(String, String) instead
      */
+    @Deprecated
     public void setAttribute(final String key, final Object value) {
         setAttribute(key, value == null? null: value.toString());
     }

src/main/java/htsjdk/samtools/MergingSamRecordIterator.java

@@ -50,8 +50,9 @@
      *
      * @param headerMerger   The merged header and contents of readers.
      * @param forcePresorted True to ensure that the iterator checks the headers of the readers for appropriate sort order.
-     * @deprecated replaced by (SamFileHeaderMerger, Collection<SAMFileReader>, boolean)
+     * @deprecated replaced by {@link #MergingSamRecordIterator(SamFileHeaderMerger, Collection, boolean)}
      */
+    @Deprecated
     public MergingSamRecordIterator(final SamFileHeaderMerger headerMerger, final boolean forcePresorted) {
         this(headerMerger, headerMerger.getReaders(), forcePresorted);
     }

src/main/java/htsjdk/samtools/SAMRecord.java

@@ -985,9 +985,10 @@ public void setProperPairFlag(final boolean flag) {
 
     /**
      * the query sequence itself is unmapped.  This method name is misspelled.
-     * Use setReadUnmappedFlag instead.
+     * Use {@link #setReadUnmappedFlag} instead.
      * @deprecated
      */
+    @Deprecated
     public void setReadUmappedFlag(final boolean flag) {
         setReadUnmappedFlag(flag);
     }
@@ -1648,8 +1649,9 @@ public int getAttributesBinarySize() {
      *
      * @return String representation of this.
      * @deprecated This method is not guaranteed to return a valid SAM text representation of the SAMRecord.
-     * To get standard SAM text representation, use htsjdk.samtools.SAMRecord#getSAMString().
+     * To get standard SAM text representation, {@link SAMRecord#getSAMString}.
      */
+    @Deprecated
     public String format() {
         final StringBuilder buffer = new StringBuilder();
         addField(buffer, getReadName(), null, null);

src/main/java/htsjdk/samtools/SAMSequenceRecord.java

@@ -82,9 +82,10 @@ private SAMSequenceRecord() {
     }
     
     /**
-     * @deprecated Use SAMSequenceRecord(final String name, final int sequenceLength) instead.
+     * @deprecated Use {@link #SAMSequenceRecord(String, int)} instead.
      * sequenceLength is required for the object to be considered valid.
      */
+    @Deprecated
     public SAMSequenceRecord(final String name) {
         this(name, UNKNOWN_SEQUENCE_LENGTH);
     }

src/main/java/htsjdk/samtools/SAMUtils.java

@@ -421,8 +421,9 @@ public static int fastqToPhred(final char ch) {
      *
      * @param beg 0-based start of read (inclusive)
      * @param end 0-based end of read (exclusive)
-     * @deprecated Use GenomicIndexUtil.regionToBin
+     * @deprecated Use {@link GenomicIndexUtil#regionToBin}
      */
+    @Deprecated
     static int reg2bin(final int beg, final int end) {
         return GenomicIndexUtil.regionToBin(beg, end);
     }

src/main/java/htsjdk/samtools/SamFileHeaderMerger.java

@@ -122,8 +122,9 @@ public int compare(final AbstractSAMHeaderRecord o1, final AbstractSAMHeaderReco
      *
      * @param readers   sam file readers to combine
      * @param sortOrder sort order new header should have
-     * @deprecated replaced by SamFileHeaderMerger(Collection<SAMFileHeader>, SAMFileHeader.SortOrder, boolean)
+     * @deprecated replaced by {@link #SamFileHeaderMerger(SAMFileHeader.SortOrder, Collection, boolean)}
      */
+    @Deprecated
     public SamFileHeaderMerger(final Collection<SamReader> readers, final SAMFileHeader.SortOrder sortOrder) {
         this(readers, sortOrder, false);
     }
@@ -135,8 +136,9 @@ public SamFileHeaderMerger(final Collection<SamReader> readers, final SAMFileHea
      * @param sortOrder         sort order new header should have
      * @param mergeDictionaries If true, merge sequence dictionaries in new header.  If false, require that
      *                          all input sequence dictionaries be identical.
-     * @deprecated replaced by SamFileHeaderMerger(Collection<SAMFileHeader>, SAMFileHeader.SortOrder, boolean)
+     * @deprecated replaced by {@link #SamFileHeaderMerger(SAMFileHeader.SortOrder, Collection, boolean)}
      */
+    @Deprecated
     public SamFileHeaderMerger(final Collection<SamReader> readers, final SAMFileHeader.SortOrder sortOrder, final boolean mergeDictionaries) {
         this(sortOrder, getHeadersFromReaders(readers), mergeDictionaries);
         this.readers = readers;
@@ -188,7 +190,7 @@ public SamFileHeaderMerger(final SAMFileHeader.SortOrder sortOrder, final Collec
         }
     }
 
-    // Utilility method to make use with old constructor
+    // Utility method to make use with old constructor
     private static List<SAMFileHeader> getHeadersFromReaders(final Collection<SamReader> readers) {
         final List<SAMFileHeader> headers = new ArrayList<SAMFileHeader>(readers.size());
         for (final SamReader reader : readers) {
@@ -585,7 +587,7 @@ private SAMSequenceDictionary mergeSequences(final SAMSequenceDictionary mergeIn
                 // Since sequenceRecord already exists in resultingDict, don't need to add it.
                 // Add in all the sequences prior to it that have been held in holder.
                 resultingDict.addAll(loc, holder);
-                // Remember the index of sequenceRecord so can check for merge imcompatibility.
+                // Remember the index of sequenceRecord so can check for merge incompatibility.
                 prevloc = loc + holder.size();
                 previouslyMerged = sequenceRecord;
                 holder.clear();
@@ -622,12 +624,12 @@ private static int getIndexOfSequenceName(final List<SAMSequenceRecord> list, fi
      * @param masterDictionary the superset dictionary we've created.
      */
     private void createSequenceMapping(final Collection<SAMFileHeader> headers, final SAMSequenceDictionary masterDictionary) {
-        final LinkedList<String> resultingDictStr = new LinkedList<String>();
+        final LinkedList<String> resultingDictStr = new LinkedList<>();
         for (final SAMSequenceRecord r : masterDictionary.getSequences()) {
             resultingDictStr.add(r.getSequenceName());
         }
         for (final SAMFileHeader header : headers) {
-            final Map<Integer, Integer> seqMap = new HashMap<Integer, Integer>();
+            final Map<Integer, Integer> seqMap = new HashMap<>();
             final SAMSequenceDictionary dict = header.getSequenceDictionary();
             for (final SAMSequenceRecord rec : dict.getSequences()) {
                 seqMap.put(rec.getSequenceIndex(), resultingDictStr.indexOf(rec.getSequenceName()));
@@ -640,8 +642,9 @@ private void createSequenceMapping(final Collection<SAMFileHeader> headers, fina
     /**
      * Returns the read group id that should be used for the input read and RG id.
      *
-     * @deprecated replaced by getReadGroupId(SAMFileHeader, String)
+     * @deprecated replaced by {@link #getReadGroupId(SAMFileHeader, String)}
      */
+    @Deprecated
     public String getReadGroupId(final SamReader reader, final String originalReadGroupId) {
         return getReadGroupId(reader.getFileHeader(), originalReadGroupId);
     }
@@ -655,8 +658,9 @@ public String getReadGroupId(final SAMFileHeader header, final String originalRe
      * @param reader                 one of the input files
      * @param originalProgramGroupId a program group ID from the above input file
      * @return new ID from the merged list of program groups in the output file
-     * @deprecated replaced by getProgramGroupId(SAMFileHeader, String)
+     * @deprecated replaced by {@link #getProgramGroupId(SAMFileHeader, String)}
      */
+    @Deprecated
     public String getProgramGroupId(final SamReader reader, final String originalProgramGroupId) {
         return getProgramGroupId(reader.getFileHeader(), originalProgramGroupId);
     }
@@ -693,8 +697,9 @@ public SAMFileHeader getMergedHeader() {
     /**
      * Returns the collection of readers that this header merger is working with. May return null.
      *
-     * @deprecated replaced by getHeaders()
+     * @deprecated replaced by {@link #getHeaders()}
      */
+    @Deprecated
     public Collection<SamReader> getReaders() {
         return this.readers;
     }
@@ -712,8 +717,9 @@ public SAMFileHeader getMergedHeader() {
      * @param reader                    the reader
      * @param oldReferenceSequenceIndex the old sequence (also called reference) index
      * @return the new index value
-     * @deprecated replaced by getMergedSequenceIndex(SAMFileHeader, Integer)
+     * @deprecated replaced by {@link #getMergedSequenceIndex(SAMFileHeader, Integer)}
      */
+    @Deprecated
     public Integer getMergedSequenceIndex(final SamReader reader, final Integer oldReferenceSequenceIndex) {
         return this.getMergedSequenceIndex(reader.getFileHeader(), oldReferenceSequenceIndex);
     }
@@ -745,15 +751,15 @@ public Integer getMergedSequenceIndex(final SAMFileHeader header, final Integer
      * Implementations of this interface are used by mergeHeaderRecords(..) to instantiate
      * specific subclasses of AbstractSAMHeaderRecord.
      */
-    private static interface HeaderRecordFactory<RecordType extends AbstractSAMHeaderRecord> {
+    private interface HeaderRecordFactory<RecordType extends AbstractSAMHeaderRecord> {
 
         /**
          * Constructs a new instance of RecordType.
          *
          * @param id        The id of the new record.
          * @param srcRecord Except for the id, the new record will be a copy of this source record.
          */
-        public RecordType createRecord(final String id, RecordType srcRecord);
+        RecordType createRecord(final String id, RecordType srcRecord);
     }
 
     /**

src/main/java/htsjdk/samtools/SamFileValidator.java

@@ -588,8 +588,9 @@ public void setBisulfiteSequenced(boolean bisulfiteSequenced) {
     }
 
     /**
-     * @deprecated use setIndexValidationStringency instead
+     * @deprecated use {@link #setIndexValidationStringency} instead
      */
+    @Deprecated
     public SamFileValidator setValidateIndex(final boolean validateIndex) {
         // The SAMFileReader must also have IndexCaching enabled to have the index validated,
         return this.setIndexValidationStringency(validateIndex ? IndexValidationStringency.EXHAUSTIVE : IndexValidationStringency.NONE);

src/main/java/htsjdk/samtools/sra/SRAAccession.java

@@ -74,10 +74,11 @@ public static void setAppVersionString(String appVersionString) {
     }
 
     /**
-     * @deprecated
      * @return true if SRA successfully loaded native libraries and fully initialized,
      * false otherwise
+     * @deprecated use {@link #checkIfInitialized} instead
      */
+    @Deprecated
     public static boolean isSupported() {
         return checkIfInitialized() == null;
     }

src/main/java/htsjdk/samtools/util/TestUtil.java

@@ -50,8 +50,9 @@ public static File getTempDirectory(final String prefix, final String suffix) {
     }
 
     /**
-     * @deprecated Use properly spelled method.
+     * @deprecated Use properly spelled method. {@link #getTempDirectory}
      */
+    @Deprecated
     public static File getTempDirecory(final String prefix, final String suffix) {
         return getTempDirectory(prefix, suffix);
     }