[ecj] VMStackWalker javadoc

[Gary Benson <gbenson@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 143 bytes --]

Hi all,

This commit adds gcj-specific javadoc to the new VMStackWalker
class in order to make it more obvious how it all works.

Cheers,
Gary

[-- Attachment #2: patch --]
[-- Type: text/plain, Size: 3452 bytes --]

Index: ChangeLog
===================================================================
--- ChangeLog	(revision 119303)
+++ ChangeLog	(working copy)
@@ -1,3 +1,7 @@
+2006-11-29  Gary Benson  <gbenson@redhat.com>
+
+	* gnu/classpath/VMStackWalker.java: Added javadoc.
+
 2006-11-27  Andrew Haley  <aph@redhat.com>
 
 	* sun/reflect/misc/ReflectUtil.java (checkPackageAccess):
Index: gnu/classpath/VMStackWalker.java
===================================================================
--- gnu/classpath/VMStackWalker.java	(revision 119303)
+++ gnu/classpath/VMStackWalker.java	(working copy)
@@ -1,5 +1,5 @@
 /* VMStackWalker.java -- Reference implementation of VM hooks for stack access
-   Copyright (C) 2005 Free Software Foundation
+   Copyright (C) 2005, 2006 Free Software Foundation
 
 This file is part of GNU Classpath.
 
@@ -50,6 +50,7 @@
  * @author John Keiser
  * @author Eric Blake <ebb9@email.byu.edu>
  * @author Archie Cobbs
+ * @author Andrew Haley <aph@redhat.com>
  */
 public final class VMStackWalker
 {
@@ -81,8 +82,11 @@
    * and should return the same result.
    *
    * <p>
-   * VM implementers are encouraged to provide a more efficient
-   * version of this method.
+   * When compiling to native code gcj translates calls to this
+   * method into calls to <code>getCallingClass(addr)</code>, with
+   * <code>addr</code> being the address of the method calling this
+   * method. <code>getCallingClass(addr)</code> does not unwind the
+   * stack, so is therefore more efficient.
    */
   public static Class getCallingClass()
     throws NotImplementedException
@@ -93,10 +97,15 @@
     return ctx[2];
   }
 
-  private static native Class getCallingClass(RawData p);
+  /**
+   * Get the class associated with the method invoking the method
+   * invoking this method, or <code>null</code> if the stack is not
+   * that deep (e.g., invoked via JNI invocation API).
+   *
+   * @param addr The address of the method invoking this method.
+   */
+  private static native Class getCallingClass(RawData addr);
 
-  private static native ClassLoader getCallingClassLoader(RawData p);
-
   /**
    * Get the class loader associated with the Class returned by
    * <code>getCallingClass()</code>, or <code>null</code> if no such class
@@ -105,8 +114,11 @@
    * and should return the same result.
    *
    * <p>
-   * VM implementers are encouraged to provide a more efficient
-   * version of this method.
+   * When compiling to native code gcj translates calls to this
+   * method into calls to <code>getCallingClassLoader(addr)</code>,
+   * with <code>addr</code> being the address of the method calling
+   * this method. <code>getCallingClassLoader(addr)</code> does not
+   * unwind the stack, so is therefore more efficient.
    */
   public static ClassLoader getCallingClassLoader()
     throws NotImplementedException
@@ -118,6 +130,15 @@
   }
 
   /**
+   * Get the class loader associated with the Class returned by
+   * <code>getCallingClass()</code>, or <code>null</code> if no
+   * such class exists or it is the boot loader.
+   * 
+   * @param addr The address of the method invoking this method.
+   */
+  private static native ClassLoader getCallingClassLoader(RawData addr);
+
+  /**
    * Retrieve the class's ClassLoader, or <code>null</code> if loaded
    * by the bootstrap loader. I.e., this should return the same thing
    * as {@link java.lang.VMClass#getClassLoader}. This duplicate version