From 2aa23056d44c96db88d7cab700243886f6c00304 Mon Sep 17 00:00:00 2001
From: Kenneth Russel <kbrussel@alum.mit.edu>
Date: Mon, 17 Apr 2006 21:26:26 +0000
Subject: 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
---
make/lib/native-taglet-1.0.jar | Bin 0 -> 2995 bytes
make/lib/native-taglet-jogl.zip | Bin 0 -> 26364 bytes
src/java/com/sun/gluegen/JavaConfiguration.java | 10 ++++++++++
src/java/com/sun/gluegen/JavaEmitter.java | 5 +++++
src/java/com/sun/gluegen/JavaMethodBindingEmitter.java | 6 +++++-
src/java/com/sun/gluegen/cgram/types/Field.java | 2 +-
.../com/sun/gluegen/cgram/types/FunctionSymbol.java | 5 +++++
src/java/com/sun/gluegen/cgram/types/FunctionType.java | 15 +++++++++++++--
src/java/com/sun/gluegen/cgram/types/PointerType.java | 2 +-
9 files changed, 40 insertions(+), 5 deletions(-)
create mode 100755 make/lib/native-taglet-1.0.jar
create mode 100755 make/lib/native-taglet-jogl.zip
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
Binary files /dev/null and b/make/lib/native-taglet-1.0.jar differ
diff --git a/make/lib/native-taglet-jogl.zip b/make/lib/native-taglet-jogl.zip
new file mode 100755
index 0000000..ff77a85
Binary files /dev/null and b/make/lib/native-taglet-jogl.zip differ
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
@@ -70,6 +70,12 @@ public class JavaConfiguration {
* directory nativeOutputDir/packageAsPath(packageName). Default is false.
*/
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
@@ -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) {
--
cgit v1.2.3