From ecb681b1c769f5fd4b2c21b5a781d625c25d0bc1 Mon Sep 17 00:00:00 2001
From: sjfink <sjfink@f5eafffb-2e1d-0410-98e4-8ec43c5233c4>
Date: Fri, 12 Jun 2009 14:25:12 +0000
Subject: [PATCH] tweak comments

git-svn-id: https://wala.svn.sourceforge.net/svnroot/wala/trunk@3655 f5eafffb-2e1d-0410-98e4-8ec43c5233c4
---
 .../callgraph/ReflectionSpecification.java    |  2 -
 .../ipa/callgraph/ShallowAnalysisScope.java   |  2 -
 .../com/ibm/wala/types/MemberReference.java   | 10 +--
 .../ibm/wala/util/DeterministicHashCode.java  |  2 -
 .../src/com/ibm/wala/util/PlatformUtil.java   |  3 -
 .../wala/util/bytecode/BytecodeStream.java    |  2 +-
 .../ibm/wala/util/ref/ReferenceCleanser.java  |  3 -
 .../util/scope/PackageExpressionFilter.java   |  5 +-
 .../ibm/wala/util/strings/UTF8Convert.java    | 70 ++++++++-----------
 .../src/com/ibm/wala/util/tables/Query.java   |  3 -
 .../com/ibm/wala/util/tables/StringTable.java |  3 -
 .../ibm/wala/util/warnings/MethodWarning.java |  3 -
 .../ibm/wala/util/warnings/WalaException.java |  1 -
 .../com/ibm/wala/util/warnings/Warning.java   | 11 +--
 .../com/ibm/wala/util/warnings/Warnings.java  |  9 +--
 15 files changed, 41 insertions(+), 88 deletions(-)

diff --git a/com.ibm.wala.core/src/com/ibm/wala/ipa/callgraph/ReflectionSpecification.java b/com.ibm.wala.core/src/com/ibm/wala/ipa/callgraph/ReflectionSpecification.java
index e8b8d9cfb..12ac9c82e 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/ipa/callgraph/ReflectionSpecification.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/ipa/callgraph/ReflectionSpecification.java
@@ -20,8 +20,6 @@ import com.ibm.wala.types.MemberReference;
 public interface ReflectionSpecification {
 
   /**
-   * @param method
-   * @param bcIndex
    * @return the TypeAbstraction which represents the set of types allocated by the new instance at the specified bytecode index; or
    *         null if not specified.
    */
diff --git a/com.ibm.wala.core/src/com/ibm/wala/ipa/callgraph/ShallowAnalysisScope.java b/com.ibm.wala.core/src/com/ibm/wala/ipa/callgraph/ShallowAnalysisScope.java
index 9c8607af0..3564b0c3a 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/ipa/callgraph/ShallowAnalysisScope.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/ipa/callgraph/ShallowAnalysisScope.java
@@ -20,8 +20,6 @@ import com.ibm.wala.util.config.AnalysisScopeReader;
 /**
  * A serializable version of {@link AnalysisScope}. Note: any information about the array class loader is lost using this
  * representation.
- * 
- * @author dpikus, yinnonh
  */
 public class ShallowAnalysisScope implements Serializable {
 
diff --git a/com.ibm.wala.core/src/com/ibm/wala/types/MemberReference.java b/com.ibm.wala.core/src/com/ibm/wala/types/MemberReference.java
index 972234fc4..3f85cefb4 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/types/MemberReference.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/types/MemberReference.java
@@ -13,10 +13,7 @@ package com.ibm.wala.types;
 import com.ibm.wala.util.strings.Atom;
 
 /**
- * Abstract superclass of MethodReference and FieldReference
- * 
- * @author sjfink
- *
+ * Abstract superclass of {@link MethodReference} and {@link FieldReference}
  */
 public abstract class MemberReference {
 
@@ -35,11 +32,6 @@ public abstract class MemberReference {
    */
   private final int hash;
 
-  /**
-   * @param type
-   * @param name
-   * @param hash
-   */
   protected MemberReference(TypeReference type, Atom name, int hash) {
     this.declaringClass = type;
     this.name = name;
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/DeterministicHashCode.java b/com.ibm.wala.core/src/com/ibm/wala/util/DeterministicHashCode.java
index 6a5925908..4dd7fad35 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/DeterministicHashCode.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/DeterministicHashCode.java
@@ -16,8 +16,6 @@ import java.util.Random;
  * a simple pseudo-random number generator.
  * 
  * This is too expensive to use in inner loops.  Deprecating.
- * 
- * @author sfink
  */
 @Deprecated
 public class DeterministicHashCode {
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/PlatformUtil.java b/com.ibm.wala.core/src/com/ibm/wala/util/PlatformUtil.java
index 665e465ab..da41d0e33 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/PlatformUtil.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/PlatformUtil.java
@@ -12,9 +12,6 @@ package com.ibm.wala.util;
 
 /**
  * Platform-specific utility functions.
- * 
- * @author manu
- * 
  */
 public class PlatformUtil {
 
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/bytecode/BytecodeStream.java b/com.ibm.wala.core/src/com/ibm/wala/util/bytecode/BytecodeStream.java
index 4620c4e27..6d5f64b2b 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/bytecode/BytecodeStream.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/bytecode/BytecodeStream.java
@@ -15,7 +15,7 @@ import com.ibm.wala.classLoader.IClass;
 import com.ibm.wala.classLoader.IMethod;
 import com.ibm.wala.shrikeBT.BytecodeConstants;
 
-/****
+/**
  * Provides minimal abstraction layer to a stream of bytecodes from the code attribute of a method.
  */
 public class BytecodeStream implements BytecodeConstants {
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/ref/ReferenceCleanser.java b/com.ibm.wala.core/src/com/ibm/wala/util/ref/ReferenceCleanser.java
index ab555db6b..65b8c9bd6 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/ref/ReferenceCleanser.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/ref/ReferenceCleanser.java
@@ -26,9 +26,6 @@ import com.ibm.wala.ipa.cha.IClassHierarchy;
  * doesn't work. Help it out.
  * 
  * It's unfortunate that this class exits.
- * 
- * @author sfink
- * 
  */
 public class ReferenceCleanser {
   
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/scope/PackageExpressionFilter.java b/com.ibm.wala.core/src/com/ibm/wala/util/scope/PackageExpressionFilter.java
index 9f23cc080..0e4a7185c 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/scope/PackageExpressionFilter.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/scope/PackageExpressionFilter.java
@@ -17,8 +17,7 @@ import com.ibm.wala.classLoader.IClass;
 import com.ibm.wala.util.collections.Filter;
 
 /**
- * A file which accepts an IClass only if the package name matches
- * a regular expression
+ * A file which accepts an {@link IClass} only if the package name matches a regular expression
  */
 public class PackageExpressionFilter implements Filter<IClass> {
 
@@ -38,7 +37,7 @@ public class PackageExpressionFilter implements Filter<IClass> {
     if (c.getName().getPackage() == null) {
       return false;
     }
-    CharSequence packageName =  c.getName().getPackage().toString();
+    CharSequence packageName = c.getName().getPackage().toString();
     Matcher m = pattern.matcher(packageName);
     return m.matches();
   }
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/strings/UTF8Convert.java b/com.ibm.wala.core/src/com/ibm/wala/util/strings/UTF8Convert.java
index 81d416303..0488d384d 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/strings/UTF8Convert.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/strings/UTF8Convert.java
@@ -16,51 +16,43 @@ import java.io.UTFDataFormatException;
 import com.ibm.wala.util.debug.Assertions;
 
 /**
- * Abstract class that contains conversion routines to/from utf8
- * and/or pseudo-utf8.  It does not support utf8 encodings of
- * more than 3 bytes.
- *
- * The difference between utf8 and pseudo-utf8 is the special
- * treatment of null.  In utf8, null is encoded as a single byte
- * directly, whereas in pseudo-utf8, it is encoded as a two-byte 
- * sequence.  See the JVM spec for more information.
- *
- * @author John Whaley
+ * Abstract class that contains conversion routines to/from utf8 and/or pseudo-utf8. It does not support utf8 encodings of more than
+ * 3 bytes.
+ * 
+ * The difference between utf8 and pseudo-utf8 is the special treatment of null. In utf8, null is encoded as a single byte directly,
+ * whereas in pseudo-utf8, it is encoded as a two-byte sequence. See the JVM spec for more information.
  */
 public abstract class UTF8Convert {
 
   /**
-   * Strictly check the format of the utf8/pseudo-utf8 byte array in
-   * fromUTF8.
+   * Strictly check the format of the utf8/pseudo-utf8 byte array in fromUTF8.
    */
   static final boolean STRICTLY_CHECK_FORMAT = false;
+
   /**
-   * Set fromUTF8 to not throw an exception when given a normal utf8
-   * byte array.
+   * Set fromUTF8 to not throw an exception when given a normal utf8 byte array.
    */
   static final boolean ALLOW_NORMAL_UTF8 = false;
+
   /**
-   * Set fromUTF8 to not throw an exception when given a pseudo utf8
-   * byte array.
+   * Set fromUTF8 to not throw an exception when given a pseudo utf8 byte array.
    */
   static final boolean ALLOW_PSEUDO_UTF8 = true;
+
   /**
    * Set toUTF8 to write in pseudo-utf8 (rather than normal utf8).
    */
   static final boolean WRITE_PSEUDO_UTF8 = true;
 
   /**
-   * Convert the given sequence of (pseudo-)utf8 formatted bytes
-   * into a String.
-   *
-   * The acceptable input formats are controlled by the
-   * STRICTLY_CHECK_FORMAT, ALLOW_NORMAL_UTF8, and ALLOW_PSEUDO_UTF8
-   * flags.
-   *
+   * Convert the given sequence of (pseudo-)utf8 formatted bytes into a String.
+   * 
+   * The acceptable input formats are controlled by the STRICTLY_CHECK_FORMAT, ALLOW_NORMAL_UTF8, and ALLOW_PSEUDO_UTF8 flags.
+   * 
    * @param utf8 (pseudo-)utf8 byte array
    * @throws UTFDataFormatException if the (pseudo-)utf8 byte array is not valid (pseudo-)utf8
    * @returns unicode string
-   * @throws IllegalArgumentException  if utf8 is null
+   * @throws IllegalArgumentException if utf8 is null
    */
   public static String fromUTF8(byte[] utf8) throws UTFDataFormatException {
     if (utf8 == null) {
@@ -88,11 +80,11 @@ public abstract class UTF8Convert {
               throw new UTFDataFormatException("invalid marker bits for double byte char at location " + (i - 2));
             if (c < '\200') {
               if (!ALLOW_PSEUDO_UTF8 || (c != '\000'))
-                throw new UTFDataFormatException(
-                  "encountered double byte char that should have been single byte at location " + (i - 2));
+                throw new UTFDataFormatException("encountered double byte char that should have been single byte at location "
+                    + (i - 2));
             } else if (c > '\u07FF')
-              throw new UTFDataFormatException(
-                "encountered double byte char that should have been triple byte at location " + (i - 2));
+              throw new UTFDataFormatException("encountered double byte char that should have been triple byte at location "
+                  + (i - 2));
           }
         } else {
           byte nnb = utf8[i++];
@@ -102,8 +94,8 @@ public abstract class UTF8Convert {
             if (((b & 0xf0) != 0xe0) || ((nb & 0xc0) != 0x80) || ((nnb & 0xc0) != 0x80))
               throw new UTFDataFormatException("invalid marker bits for triple byte char at location " + (i - 3));
             if (c < '\u0800')
-              throw new UTFDataFormatException(
-                "encountered triple byte char that should have been fewer bytes at location " + (i - 3));
+              throw new UTFDataFormatException("encountered triple byte char that should have been fewer bytes at location "
+                  + (i - 3));
           }
         }
       } catch (ArrayIndexOutOfBoundsException e) {
@@ -114,14 +106,13 @@ public abstract class UTF8Convert {
   }
 
   /**
-   * Convert the given String into a sequence of (pseudo-)utf8
-   * formatted bytes.
-   *
+   * Convert the given String into a sequence of (pseudo-)utf8 formatted bytes.
+   * 
    * The output format is controlled by the WRITE_PSEUDO_UTF8 flag.
-   *
+   * 
    * @param s String to convert
    * @returns array containing sequence of (pseudo-)utf8 formatted bytes
-   * @throws IllegalArgumentException  if s is null
+   * @throws IllegalArgumentException if s is null
    */
   public static byte[] toUTF8(String s) {
     if (s == null) {
@@ -149,7 +140,8 @@ public abstract class UTF8Convert {
 
   /**
    * Returns the length of a string's UTF encoded form.
-   * @throws IllegalArgumentException  if s is null
+   * 
+   * @throws IllegalArgumentException if s is null
    */
   public static int utfLength(String s) {
     if (s == null) {
@@ -170,10 +162,10 @@ public abstract class UTF8Convert {
 
   /**
    * Check whether the given sequence of bytes is valid (pseudo-)utf8.
-   *
+   * 
    * @param bytes byte array to check
    * @returns true iff the given sequence is valid (pseudo-)utf8.
-   * @throws IllegalArgumentException  if bytes is null
+   * @throws IllegalArgumentException if bytes is null
    */
   public static boolean check(byte[] bytes) {
     if (bytes == null) {
@@ -216,7 +208,7 @@ public abstract class UTF8Convert {
     return true;
   }
 
-  public static String fromUTF8(ImmutableByteArray s){
+  public static String fromUTF8(ImmutableByteArray s) {
     if (s == null) {
       throw new IllegalArgumentException("s is null");
     }
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/tables/Query.java b/com.ibm.wala.core/src/com/ibm/wala/util/tables/Query.java
index 30e119803..6bdb34d9d 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/tables/Query.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/tables/Query.java
@@ -19,9 +19,6 @@ import com.ibm.wala.util.collections.HashSetFactory;
 
 /**
  * Misc SQL-like support for queries on tables
- * 
- * @author sjfink
- *
  */
 public class Query {
 
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/tables/StringTable.java b/com.ibm.wala.core/src/com/ibm/wala/util/tables/StringTable.java
index 655112e21..4c72ec9e7 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/tables/StringTable.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/tables/StringTable.java
@@ -24,9 +24,6 @@ import com.ibm.wala.util.debug.Assertions;
 import com.ibm.wala.util.io.FileProvider;
 
 /**
- * @author sfink
- * @author Eran Yahav
- * @author Alexey Loginov
  */
 public class StringTable extends Table<String> implements Cloneable {
 
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/warnings/MethodWarning.java b/com.ibm.wala.core/src/com/ibm/wala/util/warnings/MethodWarning.java
index 6df13b57e..53b269ca1 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/warnings/MethodWarning.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/warnings/MethodWarning.java
@@ -13,10 +13,7 @@ package com.ibm.wala.util.warnings;
 import com.ibm.wala.types.MemberReference;
 
 /**
- *
  * A warning associated with a method
- * 
- * @author sfink
  */
 public abstract class MethodWarning extends Warning {
 
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/warnings/WalaException.java b/com.ibm.wala.core/src/com/ibm/wala/util/warnings/WalaException.java
index b14e0fe87..e9118332b 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/warnings/WalaException.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/warnings/WalaException.java
@@ -18,7 +18,6 @@ public class WalaException extends Exception {
   private static final long serialVersionUID = 3959226859263419122L;
   /**
    * @param s a message describing the failure
-   * @param cause
    */
   public WalaException(String s, Throwable cause) {
     super(s, cause);
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/warnings/Warning.java b/com.ibm.wala.core/src/com/ibm/wala/util/warnings/Warning.java
index 5d48010b1..94042b84e 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/warnings/Warning.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/warnings/Warning.java
@@ -13,11 +13,7 @@ package com.ibm.wala.util.warnings;
 import com.ibm.wala.util.debug.Assertions;
 
 /**
- * 
- * A warning message. These are ordered first by severity, and then by
- * lexicographic order.
- * 
- * @author sfink
+ * A warning message. These are ordered first by severity, and then by lexicographic order.
  */
 public abstract class Warning implements Comparable {
 
@@ -36,7 +32,7 @@ public abstract class Warning implements Comparable {
   public final static byte N_LEVELS = 6;
 
   private byte level;
-  
+
   public Warning(byte level) {
     this.level = level;
   }
@@ -112,8 +108,7 @@ public abstract class Warning implements Comparable {
   }
 
   /**
-   * Must return the same String always -- this is required by the
-   * implementation of hashCode.
+   * Must return the same String always -- this is required by the implementation of hashCode.
    */
   public abstract String getMsg();
 
diff --git a/com.ibm.wala.core/src/com/ibm/wala/util/warnings/Warnings.java b/com.ibm.wala.core/src/com/ibm/wala/util/warnings/Warnings.java
index 9e4c36578..f2ab73736 100644
--- a/com.ibm.wala.core/src/com/ibm/wala/util/warnings/Warnings.java
+++ b/com.ibm.wala.core/src/com/ibm/wala/util/warnings/Warnings.java
@@ -18,22 +18,19 @@ import com.ibm.wala.util.collections.HashSetFactory;
 
 /**
  * A global, static dictionary of warnings
- * 
- * @author sfink
  */
 public class Warnings {
-  
+
   private final static Collection<Warning> warnings = HashSetFactory.make();
-  
+
   public static synchronized boolean add(Warning w) {
     return warnings.add(w);
   }
-  
+
   public static synchronized void clear() {
     warnings.clear();
   }
 
-
   public static String asString() {
     TreeSet<Warning> T = new TreeSet<Warning>();
     T.addAll(warnings);