svn commit: r797115 - /incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaStackFrame.java

[mo...@apache.org]

Author: monteith
Date: Thu Jul 23 15:52:55 2009
New Revision: 797115

URL: http://svn.apache.org/viewvc?rev=797115&view=rev
Log:
Add updates to JavaStackFrame javadoc.

Modified:
    incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaStackFrame.java

Modified: incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaStackFrame.java
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaStackFrame.java?rev=797115&r1=797114&r2=797115&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaStackFrame.java (original)
+++ incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaStackFrame.java Thu Jul 23 15:52:55 2009
@@ -23,43 +23,61 @@
 
 
 /**
- * Represents a Java stack frame.
+ * <p>Represents a Java stack frame.</p>
+ * 
  *
  */
 public interface JavaStackFrame {
     /**
-     * Get a pointer to the base of this stack frame
+     * <p>Get a pointer to the base of this stack frame within memory.</p>
+     * <p>The layout of a <code>JavaStackFrame</code> is implementation specific.
+     * </p>
+     * 
      * @return the base pointer of the stack frame
      * @throws CorruptDataException 
      */
     ImagePointer getBasePointer() throws CorruptDataException;
     
 	/**
-     * Get the location at which the method owning this frame is currently executing
-     * @return a location object describing where the frame
-     * is executing
+     * <p>
+     * Returns the {@link JavaLocation} that represents the location of this 
+     * <code>JavaStackFrame</code> within the Java program.
+     * </p>
+     * 
+     * @return a location object describing where the frame is executing.
 	 * @throws CorruptDataException 
      * 
      * @see JavaLocation
-     * 
      */
     JavaLocation getLocation() throws CorruptDataException;
     
     /**
-     * Get the set of object roots from this stack frame.
-	 *
-     * @return an iterator of JavaReferences
+     * <p>A list of references to objects and classes from this stack frame.
+     * </p>
+	 * <p>
+	 * Returns the references to object and classes this Java Virtual Machine's implementation
+	 * considers as being kept alive by this Java stack frame. As well as references from local variables and
+	 * operations stack entries, this may also include a reference to the Java frame's class or to
+	 * an object this stack frame is keeping alive through holding its monitor.
+	 * </p>
+	 * 
+     * @return a list of JavaReferences
      */
-	List getHeapRoots();                      
+	List<JavaReference> getHeapRoots();                      
 
 	/**
 	 * 
-	 * Gets the value of a variable from a stack frame.
-	 * Returns a {@link JavaObject} for an object reference, null for a null object reference. Primitives are returned as boxed primitives.
-	 * throws CorruptDataException if object reference is incorrect, or if the float or double are set to invalid values.
+	 * <p>Gets the value of a variable from a stack frame.</p>
+	 * 
+	 * <p>Returns a {@link JavaObject} for an object reference, <code>null</code> for a null object reference.
+	 * Primitives are returned as boxed primitives.
+	 * CorruptDataException is thrown if object reference is incorrect, or if the float or double are set to invalid values.
+	 * </p>
+	 * 
+	 * @param slot - the numerical local variable slot number to retrieve.
 	 * 
 	 * @throws DataUnavailable if this method is not supported or if stack not in correct state to return variables.
-	 * @throws IndexOutOfBoundsException if an invalid slot number if passed.
+	 * @throws IndexOutOfBoundsException if an invalid slot number is passed.
 	 * 
 	 * @experimental this addition to the API is experimental and subject to change
 	 */
@@ -67,9 +85,13 @@
 	Object getVariable(int slot) throws CorruptDataException, DataUnavailable, IndexOutOfBoundsException;
 
 	/**
-	 * Gets all variables from the stack frame.
-	 * Returns a {@link java.util.List} containing the available {@link #JavaVariable} 
-	 *
+	 * <p>Gets all variables from the stack frame.</p>
+	 * <p>
+	 * Returns a {@link java.util.List} containing the available {@link JavaVariable JavaVariables}.
+	 * While the method {@link JavaMethod#getVariables()} will return all local variables for a method,
+	 * this method will return only those variables that are visible at the point of execution for this
+	 * stack frame.
+	 * </p>
 	 *@experimental this addition to the API is experimental and subject to change
 	 * 
 	 */