Fixed Issue 212: Incorporate patch to add URL links to GL javadoc

Incorporated patch from user cylab on javagaming.org forums to
generate @native tags in GL javadoc which are postprocessed using a
taglet:
  http://www.javagaming.org/forums/index.php?topic=12629.0
Modified supplied patch to restrict the @native designation to only
the function name, and to understand OpenGL data type-related suffixes
(i.e., glVertex -> glVertex3f).


git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/../svn-server-sync/gluegen/trunk@29 a78bb65f-1512-4460-ba86-f6dc96a7bf27

9 files changed, 40 insertions, 5 deletions

diff --git a/make/lib/native-taglet-1.0.jar b/make/lib/native-taglet-1.0.jar
new file mode 100755
index 0000000..ff94bac
--- /dev/null
+++ b/make/lib/native-taglet-1.0.jar
diff --git a/make/lib/native-taglet-jogl.zip b/make/lib/native-taglet-jogl.zip
new file mode 100755
index 0000000..ff77a85
--- /dev/null
+++ b/make/lib/native-taglet-jogl.zip
diff --git a/src/java/com/sun/gluegen/JavaConfiguration.java b/src/java/com/sun/gluegen/JavaConfiguration.java
index 18001aa..39c1bf3 100644
--- a/src/java/com/sun/gluegen/JavaConfiguration.java
+++ b/src/java/com/sun/gluegen/JavaConfiguration.java
@@ -71,6 +71,12 @@ public class JavaConfiguration {
    */
   private boolean nativeOutputUsesJavaHierarchy;
   /**
+   * If true, then the comment of a native method binding will include a @native tag
+   * to allow taglets to augment the javadoc with additional information regarding
+   * the mapped C function. Defaults to false.
+   */
+  private boolean tagNativeBinding;
+  /**
    * Style of code emission. Can emit everything into one class
    * (AllStatic), separate interface and implementing classes
    * (InterfaceAndImpl), only the interface (InterfaceOnly), or only
@@ -227,6 +233,8 @@ public class JavaConfiguration {
   public String      nativeOutputDir()               { return nativeOutputDir; }
   /** Returns whether the native code directory structure mirrors the Java hierarchy. */
   public boolean     nativeOutputUsesJavaHierarchy() { return nativeOutputUsesJavaHierarchy; }
+  /** Returns whether the comment of a native method binding should include a @native tag. */
+  public boolean     tagNativeBinding()              { return tagNativeBinding; }
   /** Returns the code emission style (constants in JavaEmitter) parsed from the configuration file. */
   public int         emissionStyle()                 { return emissionStyle; }
   /** Returns the access control for the emitted Java method. Returns one of JavaEmitter.ACC_PUBLIC, JavaEmitter.ACC_PROTECTED, JavaEmitter.ACC_PRIVATE, or JavaEmitter.ACC_PACKAGE_PRIVATE. */
@@ -607,6 +615,8 @@ public class JavaConfiguration {
     } else if (cmd.equalsIgnoreCase("HierarchicalNativeOutput")) {
       String tmp = readString("HierarchicalNativeOutput", tok, filename, lineNo);
       nativeOutputUsesJavaHierarchy = Boolean.valueOf(tmp).booleanValue();
+    } else if (cmd.equalsIgnoreCase("TagNativeBinding")) {
+      tagNativeBinding = readBoolean("TagNativeBinding", tok, filename, lineNo).booleanValue();
     } else if (cmd.equalsIgnoreCase("Style")) {
       String style = readString("Style", tok, filename, lineNo);
       if (style.equalsIgnoreCase("AllStatic")) {
diff --git a/src/java/com/sun/gluegen/JavaEmitter.java b/src/java/com/sun/gluegen/JavaEmitter.java
index d4bafb7..5902430 100644
--- a/src/java/com/sun/gluegen/JavaEmitter.java
+++ b/src/java/com/sun/gluegen/JavaEmitter.java
@@ -356,6 +356,7 @@ public class JavaEmitter implements GlueEmitter {
                                    writer,
                                    cfg.runtimeExceptionType(),
                                    !signatureOnly && needsBody,
+                                   cfg.tagNativeBinding(),
                                    false,
                                    cfg.nioDirectOnly(binding.getName()),
                                    false,
@@ -418,6 +419,7 @@ public class JavaEmitter implements GlueEmitter {
                                        writer,
                                        cfg.runtimeExceptionType(),
                                        false,
+                                       cfg.tagNativeBinding(),
                                        true,
                                        cfg.nioDirectOnly(binding.getName()),
                                        true,
@@ -442,6 +444,7 @@ public class JavaEmitter implements GlueEmitter {
                                          writer,
                                          cfg.runtimeExceptionType(),
                                          false,
+                                         cfg.tagNativeBinding(),
                                          true,
                                          false,
                                          true,
@@ -859,6 +862,7 @@ public class JavaEmitter implements GlueEmitter {
                                              writer,
                                              cfg.runtimeExceptionType(),
                                              true,
+                                             cfg.tagNativeBinding(),
                                              false,
                                              true, // FIXME: should unify this with the general emission code
                                              false,
@@ -874,6 +878,7 @@ public class JavaEmitter implements GlueEmitter {
                                              writer,
                                              cfg.runtimeExceptionType(),
                                              false,
+                                             cfg.tagNativeBinding(),
                                              true,
                                              true, // FIXME: should unify this with the general emission code
                                              true,
diff --git a/src/java/com/sun/gluegen/JavaMethodBindingEmitter.java b/src/java/com/sun/gluegen/JavaMethodBindingEmitter.java
index 4a0b201..b08d0e4 100644
--- a/src/java/com/sun/gluegen/JavaMethodBindingEmitter.java
+++ b/src/java/com/sun/gluegen/JavaMethodBindingEmitter.java
@@ -73,6 +73,7 @@ public class JavaMethodBindingEmitter extends FunctionEmitter
   protected boolean forDirectBufferImplementation;
   protected boolean forIndirectBufferAndArrayImplementation;
   protected boolean isUnimplemented;
+  protected boolean tagNativeBinding;
 
   protected MethodBinding binding;
 
@@ -91,6 +92,7 @@ public class JavaMethodBindingEmitter extends FunctionEmitter
                                   PrintWriter output,
                                   String runtimeExceptionType,
                                   boolean emitBody,
+                                  boolean tagNativeBinding,
                                   boolean eraseBufferAndArrayTypes,
                                   boolean directNIOOnly,
                                   boolean forImplementingMethodCall,
@@ -102,6 +104,7 @@ public class JavaMethodBindingEmitter extends FunctionEmitter
     this.binding = binding;
     this.runtimeExceptionType = runtimeExceptionType;
     this.emitBody = emitBody;
+    this.tagNativeBinding = tagNativeBinding;
     this.eraseBufferAndArrayTypes = eraseBufferAndArrayTypes;
     this.directNIOOnly = directNIOOnly;
     this.forImplementingMethodCall = forImplementingMethodCall;
@@ -120,6 +123,7 @@ public class JavaMethodBindingEmitter extends FunctionEmitter
     binding                       = arg.binding;
     runtimeExceptionType          = arg.runtimeExceptionType;
     emitBody                      = arg.emitBody;
+    tagNativeBinding              = arg.tagNativeBinding;
     eraseBufferAndArrayTypes      = arg.eraseBufferAndArrayTypes;
     directNIOOnly                 = arg.directNIOOnly;
     forImplementingMethodCall     = arg.forImplementingMethodCall;
@@ -702,7 +706,7 @@ public class JavaMethodBindingEmitter extends FunctionEmitter
     }
     protected void emitBindingCSignature(MethodBinding binding, PrintWriter writer) {      
       writer.print("<code> ");
-      writer.print(binding.getCSymbol());
+      writer.print(binding.getCSymbol().toString(tagNativeBinding));
       writer.print(" </code> ");
     }
     protected void emitEnding(FunctionEmitter emitter, PrintWriter writer) {
diff --git a/src/java/com/sun/gluegen/cgram/types/Field.java b/src/java/com/sun/gluegen/cgram/types/Field.java
index e16ffbc..996d716 100644
--- a/src/java/com/sun/gluegen/cgram/types/Field.java
+++ b/src/java/com/sun/gluegen/cgram/types/Field.java
@@ -95,7 +95,7 @@ public class Field {
       return "" + getType() + " " + getName() + ";";
     } else {
       FunctionType ft = getType().asPointer().getTargetType().asFunction();
-      return ft.toString(getName(), true) + ";";
+      return ft.toString(getName(), false, true) + ";";
     }
   }
 }
diff --git a/src/java/com/sun/gluegen/cgram/types/FunctionSymbol.java b/src/java/com/sun/gluegen/cgram/types/FunctionSymbol.java
index 50ee8cc..bc54538 100644
--- a/src/java/com/sun/gluegen/cgram/types/FunctionSymbol.java
+++ b/src/java/com/sun/gluegen/cgram/types/FunctionSymbol.java
@@ -88,6 +88,11 @@ public class FunctionSymbol {
     return getType().toString(getName());
   }
 
+  /** Helper routine for emitting native javadoc tags */
+  public String toString(boolean emitNativeTag) {
+    return getType().toString(getName(), emitNativeTag);
+  }
+
   public int hashCode() {
     if (name == null) {
       return 0;
diff --git a/src/java/com/sun/gluegen/cgram/types/FunctionType.java b/src/java/com/sun/gluegen/cgram/types/FunctionType.java
index 5e22e47..e109121 100644
--- a/src/java/com/sun/gluegen/cgram/types/FunctionType.java
+++ b/src/java/com/sun/gluegen/cgram/types/FunctionType.java
@@ -107,7 +107,11 @@ public class FunctionType extends Type {
     return toString(functionName, false);
   }
 
-  String toString(String functionName, boolean isPointer) {
+  public String toString(String functionName, boolean emitNativeTag) {
+    return toString(functionName, emitNativeTag, false);
+  }
+
+  String toString(String functionName, boolean emitNativeTag, boolean isPointer) {
     StringBuffer res = new StringBuffer();
     res.append(getReturnType());
     res.append(" ");
@@ -115,7 +119,14 @@ public class FunctionType extends Type {
       res.append("(*");
     }
     if (functionName != null) {
+      if (emitNativeTag) {
+        // Emit @native tag for javadoc purposes
+        res.append("{@native ");
+      }
       res.append(functionName);
+      if (emitNativeTag) {
+        res.append("}");
+      }
     }
     if (isPointer) {
       res.append(")");
@@ -126,7 +137,7 @@ public class FunctionType extends Type {
       Type t = getArgumentType(i);
       if (t.isFunctionPointer()) {
         FunctionType ft = t.asPointer().getTargetType().asFunction();
-        res.append(ft.toString(getArgumentName(i), true));
+        res.append(ft.toString(getArgumentName(i), false, true));
       } else if (t.isArray()) {
         res.append(t.asArray().toString(getArgumentName(i)));
       } else {
diff --git a/src/java/com/sun/gluegen/cgram/types/PointerType.java b/src/java/com/sun/gluegen/cgram/types/PointerType.java
index 3fe69a1..6202505 100644
--- a/src/java/com/sun/gluegen/cgram/types/PointerType.java
+++ b/src/java/com/sun/gluegen/cgram/types/PointerType.java
@@ -126,7 +126,7 @@ public class PointerType extends Type {
     if (!targetType.isFunction()) {
       throw new RuntimeException("<Internal error or misuse> This method is only for use when printing function pointers");
     }
-    return ((FunctionType) targetType).toString(functionName, true);
+    return ((FunctionType) targetType).toString(functionName, false, true);
   }
 
   public void visit(TypeVisitor arg) {