GLGLuegen: Enhance debug/analysis code and API comments

- Use Gluegen.debug() setting

- BuildStaticGLInfo.getExtension(name) returns a set of all extension where name occurs

- GLConfiguration.shouldIgnoreExtension() reflects all extensions,
  inclusive the renames one and gives a warning in case the symbol belongs
  to multiple extension - in debug mode!

- API comment: List all extensions, incl. the one from the renames,
  this allows having a proper list to which extensions the define/function belongs to.

4 files changed, 94 insertions, 41 deletions

diff --git a/src/jogl/classes/com/jogamp/gluegen/opengl/BuildStaticGLInfo.java b/src/jogl/classes/com/jogamp/gluegen/opengl/BuildStaticGLInfo.java
index 3131267cc..87a734e1f 100644
--- a/src/jogl/classes/com/jogamp/gluegen/opengl/BuildStaticGLInfo.java
+++ b/src/jogl/classes/com/jogamp/gluegen/opengl/BuildStaticGLInfo.java
@@ -117,13 +117,13 @@ public class BuildStaticGLInfo {
   protected static Pattern definePattern =
     Pattern.compile("\\#define ([CEW]?GL[XU]?_[A-Za-z0-9_]+)\\s*([A-Za-z0-9_]+)(.*)");
 
-  // Maps function / #define names to the names of the extensions they're declared in
-  protected Map<String, String> declarationToExtensionMap = new HashMap<String, String>();
+  // Maps function / #define names to Set of names of the extensions they're declared in
+  protected Map<String, Set<String>> declarationToExtensionMap = new HashMap<String, Set<String>>();
 
   // Maps extension names to Set of identifiers (both #defines and
   // function names) this extension declares
   protected Map<String, Set<String>> extensionToDeclarationMap = new HashMap<String, Set<String>>();
-  protected boolean debug = false;
+  protected boolean DEBUG = false;
 
     /**
      * The first argument is the package to which the StaticGLInfo class
@@ -177,7 +177,7 @@ public class BuildStaticGLInfo {
     }
 
     public void setDebug(boolean v) {
-        debug = v;
+        DEBUG = v;
     }
 
     /** Parses the supplied C header files and adds the function
@@ -206,7 +206,7 @@ public class BuildStaticGLInfo {
                     identifier = m.group(defineIdentifierGroup).trim();
                     type = 1;
                 } else if (line.startsWith("#endif")) {
-                    if (debug) {
+                    if (DEBUG) {
                         System.err.println("END ASSOCIATION BLOCK: <" + activeAssociation + ">");
                     }
                     activeAssociation = null;
@@ -216,7 +216,7 @@ public class BuildStaticGLInfo {
                         && // Handles #ifndef GL_... #define GL_...
                         !identifier.equals(activeAssociation)) {
                     addAssociation(identifier, activeAssociation);
-                    if (debug) {
+                    if (DEBUG) {
                         System.err.println("  ADDING ASSOCIATION: <" + identifier + "> <" + activeAssociation + "> ; type " + type);
                     }
                 }
@@ -224,7 +224,7 @@ public class BuildStaticGLInfo {
                 // found a new #ifndef GL_XXX block
                 activeAssociation = m.group(1).trim();
 
-                if (debug) {
+                if (DEBUG) {
                     System.err.println("BEGIN ASSOCIATION BLOCK: <" + activeAssociation + ">");
                 }
             }
@@ -245,7 +245,7 @@ public class BuildStaticGLInfo {
         }
     }
 
-    public String getExtension(String identifier) {
+    public Set<String> getExtension(String identifier) {
         return declarationToExtensionMap.get(identifier);
     }
 
@@ -350,7 +350,13 @@ public class BuildStaticGLInfo {
     // Internals only below this point
     //
     protected void addAssociation(String identifier, String association) {
-        declarationToExtensionMap.put(identifier, association);
+        Set<String> extensions = declarationToExtensionMap.get(identifier);
+        if(null == extensions) {
+            extensions = new HashSet<String>();
+            declarationToExtensionMap.put(identifier, extensions);
+        }
+        extensions.add(association);
+        
         Set<String> identifiers = extensionToDeclarationMap.get(association);
         if (identifiers == null) {
             identifiers = new HashSet<String>();
diff --git a/src/jogl/classes/com/jogamp/gluegen/opengl/GLConfiguration.java b/src/jogl/classes/com/jogamp/gluegen/opengl/GLConfiguration.java
index d03e1bd9c..c1a4facd2 100755
--- a/src/jogl/classes/com/jogamp/gluegen/opengl/GLConfiguration.java
+++ b/src/jogl/classes/com/jogamp/gluegen/opengl/GLConfiguration.java
@@ -40,6 +40,7 @@
 package com.jogamp.gluegen.opengl;
 
 import com.jogamp.gluegen.GlueEmitterControls;
+import com.jogamp.gluegen.GlueGen;
 import com.jogamp.gluegen.MethodBinding;
 import com.jogamp.gluegen.procaddress.ProcAddressConfiguration;
 import com.jogamp.gluegen.runtime.opengl.GLExtensionNames;
@@ -206,10 +207,22 @@ public class GLConfiguration extends ProcAddressConfiguration {
 
     protected boolean shouldIgnoreExtension(String symbol, boolean criteria) {
         if (criteria && glInfo != null) {
-            String extension = glInfo.getExtension(symbol);
-            if (extension != null
-                    && ignoredExtensions.contains(extension)) {
-                return true;
+            Set<String> extensionNames = glInfo.getExtension(symbol);
+            if(null!=extensionNames) {
+                for(Iterator<String> i=extensionNames.iterator(); i.hasNext(); ) {
+                    String extensionName = i.next();
+                    if (extensionName != null && ignoredExtensions.contains(extensionName)) {
+                        if (DEBUG_IGNORES) {
+                            System.err.print("Ignore symbol <" + symbol + "> of extension <" + extensionName + ">");
+                            if(extensionNames.size()==1) {
+                                System.err.println(", single .");
+                            } else {
+                                System.err.println(", WARNING MULTIPLE OCCURENCE: "+extensionNames);
+                            }
+                        }
+                        return true;
+                    }
+                }
             }
             boolean isGLEnum = GLExtensionNames.isGLEnumeration(symbol);
             boolean isGLFunc = GLExtensionNames.isGLFunction(symbol);
@@ -279,6 +292,7 @@ public class GLConfiguration extends ProcAddressConfiguration {
     public void parseGLHeaders(GlueEmitterControls controls) throws IOException {
         if (!glHeaders.isEmpty()) {
             glInfo = new BuildStaticGLInfo();
+            glInfo.setDebug(GlueGen.debug());
             for (String file : glHeaders) {
                 String fullPath = controls.findHeaderFile(file);
                 if (fullPath == null) {
diff --git a/src/jogl/classes/com/jogamp/gluegen/opengl/GLEmitter.java b/src/jogl/classes/com/jogamp/gluegen/opengl/GLEmitter.java
index a096934d0..f4658ad7b 100644
--- a/src/jogl/classes/com/jogamp/gluegen/opengl/GLEmitter.java
+++ b/src/jogl/classes/com/jogamp/gluegen/opengl/GLEmitter.java
@@ -103,6 +103,9 @@ public class GLEmitter extends ProcAddressEmitter {
             return;
         }
         for (String extension : extensionsRenamedIntoCore) {
+            if(JavaConfiguration.DEBUG_RENAMES) {
+                System.err.println("<RenameExtensionIntoCore: "+extension+" BEGIN");
+            }
             Set<String> declarations = glInfo.getDeclarations(extension);
             if (declarations != null) {
                 for (Iterator<String> iterator = declarations.iterator(); iterator.hasNext();) {
@@ -120,6 +123,9 @@ public class GLEmitter extends ProcAddressEmitter {
                     }
                 }
             }
+            if(JavaConfiguration.DEBUG_RENAMES) {
+                System.err.println("RenameExtensionIntoCore: "+extension+" END>");
+            }            
         }
     }
 
@@ -321,8 +327,8 @@ public class GLEmitter extends ProcAddressEmitter {
         }
         String symbolRenamed = def.getName();
         StringBuilder newComment = new StringBuilder();
-        newComment.append("Part of <code>");
-        if (0 == addExtensionsOfSymbols2Buffer(newComment, ", ", symbolRenamed, def.getAliasedNames())) {
+        newComment.append("Part of ");
+        if (0 == addExtensionsOfSymbols2Buffer(newComment, ", ", "; ", symbolRenamed, def.getAliasedNames())) {
             if (def.isEnum()) {
                 String enumName = def.getEnumName();
                 if (null != enumName) {
@@ -348,7 +354,6 @@ public class GLEmitter extends ProcAddressEmitter {
                 }
             }
         }
-        newComment.append("</code>");
 
         if (null != optionalComment) {
             newComment.append("<br>");
@@ -358,7 +363,48 @@ public class GLEmitter extends ProcAddressEmitter {
         super.emitDefine(def, newComment.toString());
     }
 
-    public int addExtensionsOfSymbols2Buffer(StringBuilder buf, String sep, String first, Collection<String> col) {
+    private int addExtensionListOfSymbol2Buffer(BuildStaticGLInfo glInfo, StringBuilder buf, String sep1, String name) {
+        int num = 0;
+        Set<String> extensionNames = glInfo.getExtension(name);
+        if(null!=extensionNames) {
+            for(Iterator<String> i=extensionNames.iterator(); i.hasNext(); ) {
+                String extensionName = i.next();
+                if (null != extensionName) {
+                    buf.append("<code>");
+                    buf.append(extensionName);
+                    buf.append("</code>");
+                    if (i.hasNext()) {
+                        buf.append(sep1); // same-name seperator
+                    }
+                    num++;
+                }
+            }
+        }
+        return num;
+    }
+    private int addExtensionListOfAliasedSymbols2Buffer(BuildStaticGLInfo glInfo, StringBuilder buf, String sep1, String sep2, String name, Collection<String> exclude) {
+        int num = 0;
+        if(null != name) { 
+            num += addExtensionListOfSymbol2Buffer(glInfo, buf, sep1, name); // extensions of given name
+            boolean needsSep2 = 0<num;
+            Set<String> origNames = cfg.getRenamedJavaSymbols(name);
+            if(null != origNames) {
+                for(String origName : origNames) {
+                    if(!exclude.contains(origName)) {
+                        if (needsSep2) {
+                            buf.append(sep2); // diff-name seperator
+                        }            
+                        int num2 = addExtensionListOfSymbol2Buffer(glInfo, buf, sep1, origName); // extensions of orig-name
+                        needsSep2 = num<num2;
+                        num += num2;
+                    }
+                }
+            }
+        }
+        return num;
+    }
+    
+    public int addExtensionsOfSymbols2Buffer(StringBuilder buf, String sep1, String sep2, String first, Collection<String> col) {
         BuildStaticGLInfo glInfo = getGLConfig().getGLInfo();
         if (null == glInfo) {
             throw new RuntimeException("No GLInfo for: " + first);
@@ -367,28 +413,16 @@ public class GLEmitter extends ProcAddressEmitter {
         if (null == buf) {
             buf = new StringBuilder();
         }
-        String extensionName;
-
-        Iterator<String> iter = col.iterator();
-        if (null != first) {
-            extensionName = glInfo.getExtension(first);
-            if (null != extensionName) {
-                buf.append(extensionName);
-                if (iter.hasNext()) {
-                    buf.append(sep);
-                }
-                num++;
-            }
-        }
-        while (iter.hasNext()) {
-            extensionName = glInfo.getExtension(iter.next());
-            if (null != extensionName) {
-                buf.append(extensionName);
-                if (iter.hasNext()) {
-                    buf.append(sep);
-                }
-                num++;
+
+        num += addExtensionListOfAliasedSymbols2Buffer(glInfo, buf, sep1, sep2, first, col);
+        boolean needsSep2 = 0<num;
+        for(Iterator<String> iter = col.iterator(); iter.hasNext(); ) {
+            if(needsSep2) {
+                buf.append(sep2); // diff-name seperator
             }
+            int num2 = addExtensionListOfAliasedSymbols2Buffer(glInfo, buf, sep1, sep2, iter.next(), col);
+            needsSep2 = num<num2;
+            num += num2;
         }
         return num;
     }
diff --git a/src/jogl/classes/com/jogamp/gluegen/opengl/GLJavaMethodBindingEmitter.java b/src/jogl/classes/com/jogamp/gluegen/opengl/GLJavaMethodBindingEmitter.java
index 87d870817..016674338 100755
--- a/src/jogl/classes/com/jogamp/gluegen/opengl/GLJavaMethodBindingEmitter.java
+++ b/src/jogl/classes/com/jogamp/gluegen/opengl/GLJavaMethodBindingEmitter.java
@@ -108,8 +108,8 @@ public class GLJavaMethodBindingEmitter extends ProcAddressJavaMethodBindingEmit
             String symbolRenamed = binding.getName();
             StringBuilder newComment = new StringBuilder();
 
-            newComment.append("<br>Part of <code>");
-            if (0 == glEmitter.addExtensionsOfSymbols2Buffer(newComment, ", ", symbolRenamed, binding.getAliasedNames())) {
+            newComment.append("<br>Part of ");
+            if (0 == glEmitter.addExtensionsOfSymbols2Buffer(newComment, ", ", "; ", symbolRenamed, binding.getAliasedNames())) {
                 if (glEmitter.getGLConfig().getAllowNonGLExtensions()) {
                     newComment.append("CORE FUNC");
                 } else {
@@ -121,7 +121,6 @@ public class GLJavaMethodBindingEmitter extends ProcAddressJavaMethodBindingEmit
                     throw ex;
                 }
             }
-            newComment.append("</code>");
             writer.print(newComment.toString());
         }
     }