format and tweak a comment

git-svn-id: https://wala.svn.sourceforge.net/svnroot/wala/trunk@2558 f5eafffb-2e1d-0410-98e4-8ec43c5233c4

com.ibm.wala.core/src/com/ibm/wala/types/TypeReference.java

@@ -16,14 +16,14 @@ import com.ibm.wala.util.collections.HashMapFactory;
 import com.ibm.wala.util.debug.Assertions;
 
 /**
- * A class to represent the reference in a class file to some type (class,
+ * A class to represent the reference in a class file to some type (class, primitive or array). A type reference is
- * primitive or array). A type reference is uniquely defined by
+ * uniquely defined by
  * <ul>
  * <li> an initiating class loader
  * <li> a type name
  * </ul>
- * Resolving a TypeReference to a Type can be an expensive operation. Therefore
+ * Resolving a TypeReference to a Type can be an expensive operation. Therefore we canonicalize TypeReference instances
- * we canonicalize TypeReference instances and cache the result of resolution.
+ * and cache the result of resolution.
  * 
  * @author Bowen Alpern
  * @author Dave Grove
@@ -39,8 +39,7 @@ public final class TypeReference {
    */
 
   /**
-   * Used for fast access to primitives. Primitives appear in the main
+   * Used for fast access to primitives. Primitives appear in the main dictionary also.
-   * dictionary also.
    */
   private final static Map<TypeName, TypeReference> primitiveMap = HashMapFactory.make();
 
@@ -49,9 +48,9 @@ public final class TypeReference {
    */
   private final static Map<Key, TypeReference> dictionary = HashMapFactory.make();
 
-  /*****************************************************************************
+  /*********************************************************************************************************************
    * Primitive Dispatch *
-   ****************************************************************************/
+   ********************************************************************************************************************/
 
   public final static TypeName BooleanName = TypeName.string2TypeName("Z");
 
@@ -107,9 +106,9 @@ public final class TypeReference {
 
   public final static TypeReference Void = makePrimitive(VoidName);
 
-  /*****************************************************************************
+  /*********************************************************************************************************************
    * Primitive Array Dispatch *
-   ****************************************************************************/
+   ********************************************************************************************************************/
 
   public final static TypeReference BooleanArray = findOrCreateArrayOf(Boolean);
 
@@ -127,9 +126,9 @@ public final class TypeReference {
 
   public final static TypeReference ShortArray = findOrCreateArrayOf(Short);
 
-  /*****************************************************************************
+  /*********************************************************************************************************************
    * Special object types *
-   ****************************************************************************/
+   ********************************************************************************************************************/
 
   private final static TypeName JavaLangArithmeticExceptionName = TypeName.string2TypeName("Ljava/lang/ArithmeticException");
 
@@ -264,15 +263,15 @@ public final class TypeReference {
 
   private final static TypeName JavaUtilIteratorName = TypeName.string2TypeName("Ljava/util/Iterator");
 
- public final static TypeReference JavaUtilIterator = findOrCreate(ClassLoaderReference.Primordial, JavaUtilIteratorName);
+  public final static TypeReference JavaUtilIterator = findOrCreate(ClassLoaderReference.Primordial, JavaUtilIteratorName);
 
   private final static TypeName JavaUtilVectorName = TypeName.string2TypeName("Ljava/util/Vector");
 
   public final static TypeReference JavaUtilVector = findOrCreate(ClassLoaderReference.Primordial, JavaUtilVectorName);
 
-  /*****************************************************************************
+  /*********************************************************************************************************************
    * Misc special types *
-   ****************************************************************************/
+   ********************************************************************************************************************/
 
   // TODO: Is this necessary?
   public static final TypeName[] array_interfaces = new TypeName[] { JavaIoSerializableName, JavaLangCloneableName };
@@ -317,8 +316,7 @@ public final class TypeReference {
   /**
    * Find or create the canonical TypeReference instance for the given pair.
    * 
-   * @param cl
+   * @param cl the classloader (defining/initiating depending on usage)
-   *          the classloader (defining/initiating depending on usage)
    */
   public static synchronized TypeReference findOrCreate(ClassLoaderReference cl, TypeName typeName) {
 
@@ -351,10 +349,10 @@ public final class TypeReference {
   }
 
   /**
-   * Find or create the canonical TypeReference instance for the given pair.
+   * Find or create the canonical {@link TypeReference} instance for the given pair.
    * 
-   * @param cl
+   * @param cl the classloader (defining/initiating depending on usage)
-   *          the classloader (defining/initiating depending on usage)
+   * @param typeName something like "Ljava/util/Arrays"
    */
   public static synchronized TypeReference findOrCreate(ClassLoaderReference cl, String typeName) {
     return findOrCreate(cl, TypeName.string2TypeName(typeName));
@@ -373,13 +371,10 @@ public final class TypeReference {
   }
 
   /**
-   * NB: All type names should use '/' and not '.' as a separator. eg.
+   * NB: All type names should use '/' and not '.' as a separator. eg. Ljava/lang/Class
-   * Ljava/lang/Class
    * 
-   * @param cl
+   * @param cl the classloader
-   *          the classloader
+   * @param tn the type name
-   * @param tn
-   *          the type name
    */
   protected TypeReference(ClassLoaderReference cl, TypeName tn) {
     classloader = cl;
@@ -401,8 +396,7 @@ public final class TypeReference {
   }
 
   /**
-   * TODO: specialized form of TypeReference for arrays, please. Get the element
+   * TODO: specialized form of TypeReference for arrays, please. Get the element type of for this array type.
-   * type of for this array type.
    */
   public final TypeReference getArrayElementType() {
     TypeName element = name.parseForArrayElementName();
@@ -417,9 +411,8 @@ public final class TypeReference {
   }
 
   /**
-   * Return the dimensionality of the type. By convention, class types have
+   * Return the dimensionality of the type. By convention, class types have dimensionality 0, primitives -1, and arrays
-   * dimensionality 0, primitives -1, and arrays the number of [ in their
+   * the number of [ in their descriptor.
-   * descriptor.
    */
   public final int getDimensionality() {
     return name.getDimensionality();
@@ -466,13 +459,12 @@ public final class TypeReference {
   }
 
   /**
-   * TypeReferences are canonical. However, note that two TypeReferences can be
+   * TypeReferences are canonical. However, note that two TypeReferences can be non-equal, yet still represent the same
-   * non-equal, yet still represent the same IClass.
+   * IClass.
    * 
-   * For example, the there can be two TypeReferences
+   * For example, the there can be two TypeReferences <Application,java.lang.Object> and <Primordial,java.lang.Object>.
-   * <Application,java.lang.Object> and <Primordial,java.lang.Object>. These two
+   * These two TypeReference are <bf>NOT</bf> equal(), but they both represent the IClass which is named
-   * TypeReference are <bf>NOT</bf> equal(), but they both represent the IClass
+   * <Primordial,java.lang.Object>
-   * which is named <Primordial,java.lang.Object>
    */
   @Override
   public final boolean equals(Object other) {