updated javadoc comments

git-svn-id: http://anonsvn.jboss.org/repos/javassist/trunk@204 30ef5769-5b8d-40dd-aea6-55b5d6557bb3

src/main/javassist/CtBehavior.java

@@ -51,7 +51,23 @@ public MethodInfo getMethodInfo() {
     }
 
     /**
-     * Undocumented method.  Do not use; internal-use only.
+     * Returns the MethodInfo representing the method/constructor in the
+     * class file (read only).
+     * Normal applications do not need calling this method.  Use
+     * <code>getMethodInfo()</code>.
+     *
+     * <p>The <code>MethodInfo</code> object obtained by this method
+     * is read only.  Changes to this object might not be reflected
+     * on a class file generated by <code>toBytecode()</code>,
+     * <code>toClass()</code>, etc in <code>CtClass</code>.
+     *
+     * <p>This method is available even if the <code>CtClass</code>
+     * containing this method is frozen.  However, if the class is
+     * frozen, the <code>MethodInfo</code> might be also pruned.
+     *
+     * @see #getMethodInfo()
+     * @see CtClass#isFrozen()
+     * @see CtClass#prune()
      */
     public MethodInfo getMethodInfo2() { return methodInfo; }
 

src/main/javassist/CtClass.java

@@ -51,7 +51,7 @@ public abstract class CtClass {
     /**
      * The version number of this release.
      */
-    public static final String version = "3.1RC1";
+    public static final String version = "3.1RC2";
 
     /**
      * Prints the version number and the copyright notice.
@@ -215,7 +215,22 @@ public ClassFile getClassFile() {
     }
 
     /**
-     * Undocumented method.  Do not use; internal-use only.
+     * Returns a class file for this class (read only).
+     * Normal applications do not need calling this method.  Use
+     * <code>getClassFile()</code>.
+     *
+     * <p>The <code>ClassFile</code> object obtained by this method
+     * is read only.  Changes to this object might not be reflected
+     * on a class file generated by <code>toBytecode()</code>,
+     * <code>toClass()</code>, etc.
+     *
+     * <p>This method is available even if <code>isFrozen()</code>
+     * is true.  However, if the class is frozen, it might be also
+     * pruned.
+     *
+     * @see CtClass#getClassFile()
+     * @see CtClass#isFrozen()
+     * @see CtClass#prune()
      */
     public ClassFile getClassFile2() { return null; }
 
@@ -1029,8 +1044,8 @@ public void detach() {
     public void stopPruning(boolean stop) {}
 
     /**
-     * Discards unnecessary data, in particuar, <code>CodeAttribute</code>s
-     * (method bodies) of the class,
+     * Discards unnecessary attributes, in particuar,
+     * <code>CodeAttribute</code>s (method bodies) of the class,
      * to minimize the memory footprint.
      * After calling this method, the class is read only.
      * It cannot be modified any more.
@@ -1040,9 +1055,14 @@ public void stopPruning(boolean stop) {}
      * However, the method names and signatures in the class etc.
      * are still accessible.
      *
+     * <p><code>toBytecode()</code>, <code>writeFile()</code>, and
+     * <code>toClass()</code> internally call this method. 
+     *
      * @see #toBytecode()
      * @see #toClass()
      * @see #writeFile()
+     * @see #instrument(CodeConverter)
+     * @see #instrument(ExprEditor)
      *
      * @see #stopPruning(boolean)
      */

src/main/javassist/CtField.java

@@ -171,7 +171,23 @@ public FieldInfo getFieldInfo() {
     }
 
     /**
-     * Undocumented method.  Do not use; internal-use only.
+     * Returns the FieldInfo representing the field in the class
+     * file (read only).
+     * Normal applications do not need calling this method.  Use
+     * <code>getFieldInfo()</code>.
+     *
+     * <p>The <code>FieldInfo</code> object obtained by this method
+     * is read only.  Changes to this object might not be reflected
+     * on a class file generated by <code>toBytecode()</code>,
+     * <code>toClass()</code>, etc in <code>CtClass</code>.
+     *
+     * <p>This method is available even if the <code>CtClass</code>
+     * containing this field is frozen.  However, if the class is
+     * frozen, the <code>FieldInfo</code> might be also pruned.
+     *
+     * @see #getFieldInfo()
+     * @see CtClass#isFrozen()
+     * @see CtClass#prune()
      */
     public FieldInfo getFieldInfo2() { return fieldInfo; }
 

tutorial/tutorial.html

@@ -114,21 +114,27 @@ <h4>Defining a new class</h4>
 <code>abstractMethod()</code> in <code>CtNewMethod</code>.
 Note that an interface method is an abstract method.
 
-
-<h4>Frozen classes</h4>
+<a name="frozenclasses">
+<h4>Frozen classes</h4></a>
 
 <p>If a <code>CtClass</code> object is converted into a class file by
 <code>writeFile()</code>, <code>toClass()</code>, or
 <code>toBytecode()</code>, Javassist freezes that <code>CtClass</code>
 object.  Further modifications of that <code>CtClass</code> object are
-not permitted.
+not permitted.  This is for warning the developers when they attempt
+to modify a class file that has been already loaded since the JVM does
+not allow reloading a class.
 
 <p>When Javassist freezes a <code>CtClass</code> object, it also
 prunes the data structure contained in that object.  To reduce memory
-consumption, Javassist discards some part of data structure, for
-example, the data of method bodies.  Thus, after a
+consumption, Javassist discards unnecessary attributes
+(<code>attribute_info</code> structures) in that object.
+For example, <code>Code_attribute</code> structures (method bodies)
+are discarded.
+Thus, after a
 <code>CtClass</code> object is pruned, the bytecode of a method is not
-accessible although method names and signatures are accessible.
+accessible although method names, signatures, and annotations
+are still accessible.
 
 <p>To disallow pruning a <code>CtClass</code>, <code>stopPruning()</code>
 must be called in advance:
@@ -283,7 +289,8 @@ <h4>Avoid out of memory</h4>
 This specification of <code>ClassPool</code> may cause huge memory
 consumption if the number of <code>CtClass</code> objects becomes
 amazingly large (this rarely happens since Javassist tries to reduce
-memory consumption in various ways).  To avoid this problem, you
+memory consumption in <a href="#frozenclasses">various ways</a>).
+To avoid this problem, you
 can explicitly remove an unnecessary <code>CtClass</code> object from
 the <code>ClassPool</code>.  If you call <code>detach()</code> on a
 <code>CtClass</code> object, then that <code>CtClass</code> object is