# HG changeset patch
# User Matthias Grimmer <grimmer@ssw.jku.at>
# Date 1391588663 -3600
# Node ID e30bae026c936bf937cdb8fcc1cb3453a4dab0c2
# Parent  38c7543192e7bed9b24de349b5aaf7c9d5799668
GNFI: add JavaDoc

diff -r 38c7543192e7 -r e30bae026c93 graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeFunctionHandle.java
--- a/graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeFunctionHandle.java	Tue Feb 04 17:12:12 2014 -0800
+++ b/graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeFunctionHandle.java	Wed Feb 05 09:24:23 2014 +0100
@@ -23,7 +23,16 @@
 package com.oracle.graal.api.code;
 
 /**
- * The function handle of a native foreign function.
+ * The handle of a native foreign function. Use a {@code NativeFunctionHandle} to invoke native
+ * target functions.
+ * <p>
+ * The user of a {@code NativeFunctionHandle} has to pack the boxed arguments into an
+ * {@code Object[]} according to the ABI of the target platform (e.g. Unix AMD64 system:
+ * {@link "http://www.uclibc.org/docs/psABI-x86_64.pdf"}). The {@code NativeFunctionHandle} unboxes
+ * the arguments and places them into the right location (register / stack) according to the ABI.
+ * <p>
+ * A {@code NativeFunctionHandle} returns the boxed return value of the native target function. The
+ * boxed value is the return value as specified by the ABI.
  */
 public interface NativeFunctionHandle {
 
diff -r 38c7543192e7 -r e30bae026c93 graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeFunctionInterface.java
--- a/graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeFunctionInterface.java	Tue Feb 04 17:12:12 2014 -0800
+++ b/graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeFunctionInterface.java	Wed Feb 05 09:24:23 2014 +0100
@@ -23,8 +23,16 @@
 package com.oracle.graal.api.code;
 
 /**
- * Interface to resolve pointers to native foreign functions.
- * 
+ * Interface to resolve a {@code NativeFunctionHandle} or a {@code NativeFunctionPointer} to a
+ * native foreign function and a {@code NativeLibraryHandle} of a library. A
+ * {@code NativeFunctionPointer} wraps the raw function pointer. A {@code NativeFunctionHandle} is a
+ * callable representation of a native target function in Java.
+ * <p>
+ * To resolve a {@code NativeFunctionHandle}, one has to provide the signature of the native target
+ * function according to the calling convention of the target platform (e.g. Unix AMD64:
+ * {@link "http://www.uclibc.org/docs/psABI-x86_64.pdf"}). The signature contains the type (e.g.
+ * {@code int.class} for a C integer, ( {@code long.class} for a 64bit pointer) of each value, which
+ * is passed to the native target function.
  */
 public interface NativeFunctionInterface {
 
diff -r 38c7543192e7 -r e30bae026c93 graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeFunctionPointer.java
--- a/graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeFunctionPointer.java	Tue Feb 04 17:12:12 2014 -0800
+++ b/graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeFunctionPointer.java	Wed Feb 05 09:24:23 2014 +0100
@@ -22,6 +22,12 @@
  */
 package com.oracle.graal.api.code;
 
+/**
+ * Wraps the raw function pointer value.
+ * <p>
+ * Use the {@code NativeFunctionInterface} to resolve a {@code NativeFunctionHandle} of this pointer
+ * to invoke the native target function.
+ */
 public interface NativeFunctionPointer {
 
     /**
diff -r 38c7543192e7 -r e30bae026c93 graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeLibraryHandle.java
--- a/graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeLibraryHandle.java	Tue Feb 04 17:12:12 2014 -0800
+++ b/graal/com.oracle.graal.api.code/src/com/oracle/graal/api/code/NativeLibraryHandle.java	Wed Feb 05 09:24:23 2014 +0100
@@ -24,6 +24,9 @@
 
 /**
  * The library handle of the native library.
+ * <p>
+ * The {@code NativeFunctionInterface} can use a {@code NativeLibraryHandle} to look up a
+ * {@code NativeFunctionPointer} or a {@code NativeFunctionHandle} in this library.
  */
 public interface NativeLibraryHandle {
 
diff -r 38c7543192e7 -r e30bae026c93 graal/com.oracle.graal.compiler/src/com/oracle/graal/compiler/target/HostBackend.java
--- a/graal/com.oracle.graal.compiler/src/com/oracle/graal/compiler/target/HostBackend.java	Tue Feb 04 17:12:12 2014 -0800
+++ b/graal/com.oracle.graal.compiler/src/com/oracle/graal/compiler/target/HostBackend.java	Wed Feb 05 09:24:23 2014 +0100
@@ -24,6 +24,9 @@
 
 import com.oracle.graal.api.code.*;
 
+/**
+ * Common functionality of host backends.
+ */
 public interface HostBackend {
     NativeFunctionInterface getNativeFunctionInterface();
 }