# HG changeset patch
# User Pavel Tisnovsky <ptisnovs@redhat.com>
# Date 1337158785 -7200
# Node ID b6c8372f572305badccf7f71dd1d8c6f2ad428ef
# Parent  ed99188fff204c59d7f988120d64d6fd50666116
* src/ClassInfo.java:
* src/FileUtils.java:
* src/PrintClassList.java:
* src/PrintPublicMethods.java:
* src/PrintTestCoverage.java:
* src/ReportGenerator.java:
Minor changes - JavaDoc and refactoring.

diff -r ed99188fff20 -r b6c8372f5723 ChangeLog
--- a/ChangeLog	Tue May 15 17:50:12 2012 +0200
+++ b/ChangeLog	Wed May 16 10:59:45 2012 +0200
@@ -1,3 +1,13 @@
+2012-05-16  Pavel Tisnovsky  <ptisnovs@redhat.com>
+
+	* src/ClassInfo.java:
+	* src/FileUtils.java:
+	* src/PrintClassList.java:
+	* src/PrintPublicMethods.java:
+	* src/PrintTestCoverage.java:
+	* src/ReportGenerator.java:
+	Minor changes - JavaDoc and refactoring.
+
 2012-05-15  Pavel Tisnovsky  <ptisnovs@redhat.com>
 
 	* src/ReportGenerator.java:
diff -r ed99188fff20 -r b6c8372f5723 src/ClassInfo.java
--- a/src/ClassInfo.java	Tue May 15 17:50:12 2012 +0200
+++ b/src/ClassInfo.java	Wed May 16 10:59:45 2012 +0200
@@ -44,10 +44,10 @@
 
 
 /**
- * Instances of this class contain information about one tested class.
- * There are three sets of strings stored for each class: set of methods
- * contained in standard API, set of methods called from tests and the
- * union of previous two sets. These information are used by test reporter.
+ * Instances of this class contain information about one tested class. There are
+ * three sets of strings stored for each class: set of methods contained in
+ * standard API, set of methods called from tests and the union of previous two
+ * sets. These information are used by the test reporter.
  * 
  * @author Pavel Tisnovsky <ptisnovs@redhat.com>
  */
@@ -64,7 +64,7 @@
     private Set<String> testedMethods;
 
     /**
-     * Union of apiMethods and testedMethods.
+     * Union of both apiMethods and testedMethods sets.
      */
     private Set<String> allMethods;
 
diff -r ed99188fff20 -r b6c8372f5723 src/FileUtils.java
--- a/src/FileUtils.java	Tue May 15 17:50:12 2012 +0200
+++ b/src/FileUtils.java	Wed May 16 10:59:45 2012 +0200
@@ -50,9 +50,11 @@
 import java.util.LinkedList;
 import java.util.List;
 
+
+
 /**
- * Basic file utilities to avoid boring file handling.
- *
+ * Basic file utilities to avoid boring file handling using standard Java API.
+ * 
  * @author Pavel Tisnovsky
  */
 class FileUtils
@@ -303,6 +305,7 @@
         int i1 = readOneByte(fileInputStream);
         int i2 = readOneByte(fileInputStream);
         // combine all two read bytes into a word
+        // (we don't care about signed/unsigned differences at this moment)
         return (i1 << 8) | (i2);
     }
 
@@ -322,7 +325,8 @@
         int i2 = readOneByte(fileInputStream);
         int i3 = readOneByte(fileInputStream);
         int i4 = readOneByte(fileInputStream);
-        // combine all four read bytes into a word
+        // combine all four read bytes into a 32bit word
+        // (we don't care about signed/unsigned differences at this moment)
         return (i1 << 24) | (i2 << 16) | (i3 << 8) | (i4);
     }
 
diff -r ed99188fff20 -r b6c8372f5723 src/PrintClassList.java
--- a/src/PrintClassList.java	Tue May 15 17:50:12 2012 +0200
+++ b/src/PrintClassList.java	Wed May 16 10:59:45 2012 +0200
@@ -49,11 +49,12 @@
 
 /**
  * This class is used to generate and print list of all public classes which are
- * stored in specified JAR archive. This JAR archive should be accessible
+ * stored in a specified JAR archive. This JAR archive should be accessible
  * through classloader (this means that -cp should be used in certain
  * situations).
  * 
- * This tool could be used (and is plannet to be used) against "rt.jar"
+ * This tool could be used (and is planned to be used) against "rt.jar"
+ * which is usually stored in /usr/lib/jvm/java-{$version}/jre/lib/
  * 
  * @author Pavel Tisnovsky
  */
@@ -72,11 +73,11 @@
      */
     private static void generateClassList(String pathToJarArchive) {
         // it's better to print sorted class names
-        // and TreeSet sorted its elements by default
+        // and the collection type TreeSet sorted its elements by default
         Set<String> setOfClassNames = new TreeSet<String>();
         // try to read all public classes from Java archive
         readAllPublicClassesFromJarFile(pathToJarArchive, setOfClassNames);
-        // now we have the list filled, time to print them
+        // now we have the list filled and sorted, time to print them
         printAllPublicClassNames(setOfClassNames);
     }
 
@@ -95,7 +96,7 @@
             // open the archive and acquire all its entries
             jarFile = new JarFile(pathToJarArchive);
 
-            // entries inside Java archive
+            // entries inside the Java archive
             Enumeration<JarEntry> entries = jarFile.entries();
 
             // test each JAR entry
@@ -103,6 +104,7 @@
                 JarEntry entry = entries.nextElement();
                 String className = generateClassName(entry.getName());
                 // only public classes are interesting at this moment
+                // (private classes could not be tested)
                 if (isPublicClass(className)) {
                     setOfClassNames.add(className);
                 }
@@ -132,6 +134,7 @@
      */
     private static void printAllPublicClassNames(Set<String> setOfClassNames)
     {
+        // print all names of public classes
         for (String className : setOfClassNames) {
             System.out.println(className);
         }
@@ -190,7 +193,8 @@
     {
         String out = name;
         int postfixIndex = out.indexOf(".class");
-        // remove postfix if its present in name
+        // remove postfix if its present in a name
+        // (should be)
         if (postfixIndex > 0)
         {
             out = out.substring(0, postfixIndex);
@@ -217,6 +221,7 @@
             pathToRtJar = args[0];
         }
         System.err.println("Path to Jar file is set to: " + pathToRtJar);
+        // generate and print sorted list of public all classes
         generateClassList(pathToRtJar);
     }
 
diff -r ed99188fff20 -r b6c8372f5723 src/PrintPublicMethods.java
--- a/src/PrintPublicMethods.java	Tue May 15 17:50:12 2012 +0200
+++ b/src/PrintPublicMethods.java	Wed May 16 10:59:45 2012 +0200
@@ -42,27 +42,33 @@
 import java.util.Set;
 import java.util.TreeSet;
 
+
+
 /**
  * This class generates a list containing all public methods and its argument
- * types and return type for all classes specified in a file "class_list.txt"
- * or in a file specified by a command line parameter.
+ * types and return type for all classes stored in a test file "class_list.txt"
+ * or in a text file specified by a command line parameter.
  * 
  * @author Pavel Tisnovsky
  */
 public class PrintPublicMethods
 {
     /**
-     * Get a Class instance for a given class name or null if something goes
-     * wrong.
+     * Return a Class instance for a given class name or null value if something
+     * goes wrong.
      * 
      * @param className
      *            name of a class (including package name)
-     * @return Class instance
+     * @return Class instance for a given class name. Null value is returned if
+     *         something goes wrong, ie. class could not be found or it's not a
+     *         public class etc.
      */
     @SuppressWarnings("unchecked")
     private static Class getClass(String className) {
+        // variable to be returned from this method
         Class clazz = null;
         try {
+            // try to get a class for given class name
             clazz = Class.forName(className);
             // we need to get a list of public classes only
             // (Interfaces and non public classes is not interesting ATM)
@@ -84,19 +90,20 @@
             return null;
         }
         catch (NoClassDefFoundError e) {
-            // it might happen
+            // it might also happen
             return null;
         }
         // it is not a class at all or the class is not public
+        // only null value is returned
         return null;
     }
 
     /**
      * Remove "public", "static", "final", "synchronized" and "native" prefixes
-     * from full method name;
+     * from full method name.
      * 
      * @param methodName
-     *            method name with all prefixes
+     *            method name containing possibly some prefixes
      * @return method name without prefixes
      */
     private static String acquireMethodName(String methodName) {
@@ -108,6 +115,7 @@
             // remove one prefix
             methodNameString = removePrefix(methodNameString, prefix);
         }
+        // "throws" declaration should be removed too
         return removeThrowsFromDeclaration(methodNameString);
     }
 
@@ -118,7 +126,7 @@
      *            method name that could contains prefix.
      * @param prefix
      *            prefix to be removed.
-     * @return method name without prefixes
+     * @return method name without the selected prefix
      */
     private static String removePrefix(String methodName, String prefix) {
         String prefixStr = prefix + " ";
@@ -138,9 +146,12 @@
      * is changed to:
      * 
      * <pre>
-     * void java.lang.Object.wait() throws java.lang.InterruptedException
+     * void java.lang.Object.wait()
      * </pre>
-     * 
+     *
+     * When the method does not contain "throws" declaration, it's name is not
+     * changed.
+     *
      * @param methodName
      *            method name which could contain throws declaration
      * @return method name without throws declaration
@@ -168,6 +179,7 @@
         if (clazz == null) {
             return out;
         }
+        // retrieve all declared methods
         Method[] methods = clazz.getDeclaredMethods();
         // process all methods select add only public ones
         for (Method method : methods) {
@@ -180,8 +192,7 @@
     }
 
     /**
-     * Get all public methods from given class name (if such class exists).
-     * 
+     * Get all public constructors from given class name (if such class exists).
      * 
      * @param className
      *            name of a class (including package name)
@@ -195,6 +206,7 @@
         if (clazz == null) {
             return out;
         }
+        // get all declared constructors
         Constructor[] constructors = clazz.getConstructors();
         // process all constructors select add only public ones
         for (Constructor constructor : constructors) {
@@ -214,7 +226,9 @@
      */
     private static void printAllPublicMethodsAndConstructors(String className)
     {
+        // get and print all public constructors 
         printAllConstructors(className);
+        // get and print all public methods 
         printAllPublicMethods(className);
     }
 
@@ -263,6 +277,7 @@
         }
         else
         {
+            // used did not specified class list
             System.err.println("Usage java PrintPublicMethods package.className");
         }
     }
diff -r ed99188fff20 -r b6c8372f5723 src/PrintTestCoverage.java
--- a/src/PrintTestCoverage.java	Tue May 15 17:50:12 2012 +0200
+++ b/src/PrintTestCoverage.java	Wed May 16 10:59:45 2012 +0200
@@ -57,20 +57,53 @@
  */
 enum ConstantPoolTag
 {
+    /**
+     * Reference to a class name.
+     */
     CONSTANT_Class(7),
+    /**
+     * Reference to a field.
+     */
     CONSTANT_Fieldref(9),
-    CONSTANT_Methodref(10), 
+    /**
+     * Reference to a method.
+     */
+    CONSTANT_Methodref(10),
+    /**
+     * Reference to an interface method.
+     */
     CONSTANT_InterfaceMethodref(11),
+    /**
+     * Reference to a string.
+     */
     CONSTANT_String(8),
+    /**
+     * Integer constant.
+     */
     CONSTANT_Integer(3),
+    /**
+     * Float constant.
+     */
     CONSTANT_Float(4),
+    /**
+     * Long constants (it occupies two constant pool entries).
+     */
     CONSTANT_Long(5),
+    /**
+     * Double constant (it occupies two constant pool entries).
+     */
     CONSTANT_Double(6),
+    /**
+     * Name and type tuple.
+     */
     CONSTANT_NameAndType(12),
+    /**
+     * UTF-8 encoded string.
+     */
     CONSTANT_Utf8(1);
 
     /**
-     * Value represented one enumeration item.
+     * Value which represents one enumeration item.
      */
     private int value;
 
@@ -96,17 +129,23 @@
     }
 
     /**
-     * Converts integer value to a enumeration item.
-     *
-     * @param value integer value
+     * Converts integer value to an enumeration item. Null is returned if the
+     * given value does not correspond to any constant pool type.
+     * 
+     * @param value
+     *            integer value
      * @return selected enumeration item or null
      */
     public static ConstantPoolTag intToConstantPoolTag(int value)
     {
+        // loop over all known values
+        // and try to find the particular value
         for (ConstantPoolTag val : values())
         {
+            // if value is found
             if (val.value == value)
             {
+                // return it
                 return val;
             }
         }
@@ -115,7 +154,7 @@
 }
 
 /**
- * Abstract class which represents any constant pool record.
+ * Abstract class which could represent any constant pool record.
  * 
  * @author Pavel Tisnovsky
  */
@@ -177,14 +216,25 @@
 }
 
 /**
- * Class representing class record stored in constant pool.
+ * Class representing class record stored in a constant pool.
  * 
  * @author Pavel Tisnovsky
  */
 class ClassRecord extends ConstantPoolRecord
 {
+    /**
+     * Reference to a class name stored itself in constant pool.
+     */
     private int classNameIndex;
 
+    /**
+     * Constructor with initialization code.
+     * 
+     * @param tag
+     *            tag associated with each constant pool record.
+     * @param classNameIndex
+     *            reference to a class name stored itself in constant pool
+     */
     public ClassRecord(ConstantPoolTag tag, int classNameIndex)
     {
         super(tag);
diff -r ed99188fff20 -r b6c8372f5723 src/ReportGenerator.java
--- a/src/ReportGenerator.java	Tue May 15 17:50:12 2012 +0200
+++ b/src/ReportGenerator.java	Wed May 16 10:59:45 2012 +0200
@@ -690,11 +690,7 @@
 
         System.out.println("Report directory:  " + reportDirectory);
 
-        Map<String, ClassInfo> classInfoMap = new HashMap<String, ClassInfo>();
-        for (String className : allClasses)
-        {
-            classInfoMap.put(className, new ClassInfo(reportDirectory, className));
-        }
+        Map<String, ClassInfo> classInfoMap = prepareClassInfoMap(reportDirectory, allClasses);
 
         printPackageListToFile(reportDirectory, allClasses, testedClasses, usedPackageNames, classInfoMap);
         printReportForAllClassesInOneFile(reportDirectory, usedPackageNames, testedClasses, classInfoMap);
@@ -704,6 +700,21 @@
     }
 
     /**
+     * @param reportDirectory
+     * @param allClasses
+     * @return
+     */
+    private static Map<String, ClassInfo> prepareClassInfoMap(String reportDirectory, Set<String> allClasses)
+    {
+        Map<String, ClassInfo> classInfoMap = new HashMap<String, ClassInfo>();
+        for (String className : allClasses)
+        {
+            classInfoMap.put(className, new ClassInfo(reportDirectory, className));
+        }
+        return classInfoMap;
+    }
+
+    /**
      * Entry point to the report generator.
      * 
      * @param args