Javadoc Doclet for referencing existing GL documentation from JOGL javadoc

OpenGL Development JOGL Development
#1

As suggested in other threads, I prototyped a doclet to link glXXX methods to external webpages. The result can be seen here (only the 160+ methods from the bluebook 1.0 are linked…take a Look at the glAccum for example)

Writing the doclet was a major pain in the a… and I am still unable to make this work for different JDK platforms, so I doubt this is the way to go (I am seriously shocked by the javadoc doclet api, respectively the default implementation)

The right way to implement custom links in the javadoc seem to be taglets, which feature a much cleaner and simpler api. To be able to use this feature, the gluegen has to augment the javadoc comments with a custom inline tag, like {@native void glBegin(GLenum mode)}. This way I can write a Taglet, that wires the online-reference or whatever to the javadoc.

So Ken, what do you think?

#2

That sounds pretty simple. Do you think you could prototype this in your workspace? If you check out the gluegen and jogl workspaces and get things set up according to the build instructions, you can just modify the DefaultCommentEmitter in JavaMethodBindingEmitter.java (around line 687); just edit emitBindingCSignature. If you can easily insert the appropriate text (like “@native{” / “}”) around the function name and transform it in your taglet, we can easily add a configuration file option to cause that tag to be emitted.

#3

No problem, I have already set up the build system. I will have a look next week.

#4

What might simplify your code is linking to opengl.org. That site has a page per function of the form

http://www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/(gl|glu)/<function name>.html

I’m guessing this will be a lot simpler than indexing that one big page.
The pages on the 3dlabs developer site have a similar structure.

#5

Thanks for the pointer.

Actually I just a tool that scans all links in the Bluebook TOC for content starting with gl, so It was fairly simple. But having one page per function is even better IMHO

#6

Finally I found the time to work on this again. You can download the prototype here.

The contents of the readme file:


This package contains the taglet prototype to generate links to existing
documentation for JOGL native calls.

Author:   Mathias Henze
Licence:  Unrestricted usage and distribution in source and binary form.
Warranty: None. The author is not responsible for any physical or mental
          damage caused by the use of this software =)

CONTENTS
========

BluebookReferenceGenerator .... The sources of a tool to generate the needed
                                mapping-file from a website
native-taglet ................. The sources of the taglet to evaluate @native
                                tags in javadoc comments
native-taglet-1.0.jar ......... The compiled version of the taglet, ready for
                                inclusion in the javadoc build process
native-taglet.properties ...... The configuration file of the native taglet,
                                that contains the mapping from names to URLs
gluegen-src-patch.txt ......... The patch to the gluegen src-directory to
                                enable @native tag generation inside gluegen
Readme.txt .................... This file ;)


USAGE
=====
- Put the "native-taglet-1.0.jar" in the "jogl/make" directory
- Put the "native-taglet.properties" in the "jogl/make" directory
- Patch the gluegen sources using "gluegen-src-patch.txt"
- Add the line "TagNativeBinding true" to the gluegen configuration files
  (gl-<platform>.cfg, glu-<platform>.cfg)
- Nest the line
  <taglet name="net.highteq.nativetaglet.NativeTaglet" path="native-taglet-1.0.jar"/>
  inside the <javadoc>-tags in the file "jogl/make/build.xml"
- run "ant javadoc" from the commandline in "jogl/make"

NOTES
=====
The "BluebookReferenceGenerator" is a Netbeans project and requires "JTidy"
(http://sourceforge.net/projects/jtidy), DOM4J (http://www.dom4j.org/) and
jaxon (http://jaxen.codehaus.org/)

The "native-taglet" compiles fine without Netbeans but includes a project
folder for convenience. The build file asumes tht JAVA_HOME variable to
point to a valid JDK since the compilation requires the "tools.jar"

The patch to gluegen adds the "TagNativeBinding" configuration option to
the "JavaConfiguration" class which defaults to "false". The patch also adds
the @native tag generation to the "JavaMethodBindingEmitter" class. Therefor
it changes to base class JavaEmitter, too.

The "native-taglet.properties" contains simple <name>=<URL> mappings, where
<name> ist the name of the native method and <URL> is a location relative to
the URL mapped by the "nativetaglet.baseUrl" key.

===

  Enjoy!
#7

Thanks! This looks great. I’ve filed Issue 212 to track this and will try to incorporate it soon.

#8

Thanks again for this patch. In trying to incorporate it I’ve run into an issue. The BluebookReferenceGenerator picks up the abstract names for routines like glVertex instead of the more concrete names like glVertex3f, glVertex2dv, etc. With the original sources this means that such routines won’t have any links generated due to how the regexp in the taglet tried to match the keys in the native-taglet.properties files.

I’ve tried a couple of workarounds, neither of which works. The current sources attached to this post surround only the function name with the native tag, not the entire signature, which should make the problem simpler; however, the naming rules are not easy to encapsulate. Consider for example the difference between glVertexAttribPointerARB (which should not match to glVertex) and glVertex2dv, which should. One might consider a set of well-known suffixes to try. What about vendor-specific extensions like glVertex3hNV? Should this match to glVertex or not given that it is in a separate package?

Basically I think the BluebookReferenceGenerator needs to descend further into the document structure to find the concrete names of the functions documented rather than the abstract name so that an exact match can always be done in the native-taglet.properties. Could you make this change?

Edit: sources are here.

#9

To follow up to my own post: I tried the approach of a set of well-known suffixes and it seems to have addressed the problem pretty well. Thanks again for your patch; it’s been checked in to the JOGL source tree. The javadoc links should start showing up in tomorrow’s (4/18) nightly build.

To the community: at this point what we need the most in this area is work on jogl/make/native-taglet.properties in the source tree. If people could start going through the extension registry (or write a program to crawl it) and figure out the mappings from the various functions like glBindFramebufferEXT to the extension in which they’re documented, and add these links to the properties file, that would be great. I think we’ll need a little more work on the native taglet as well to support both absolute and relative URLs on the right-hand side.

#10

Thanks for applying this patch. I will take a look at your changes and try to come up with a better link-generator. Maybe the native-taglet sould be configurable to produce a template properties-file containing the names of all the tagged native functions, so the generator tool can scan the online documentation for concrete function names and not just for glXXX.

[quote]I think we’ll need a little more work on the native taglet as well to support both absolute and relative URLs on the right-hand side.
[/quote]
Could you please provide the latest version of the taglet? The one from the post above seems not to contain your “known-suffix-workaround”. How do we handle the sources in the future? One option would be to incorporate the native-taglet into the gluegen source tree…

#11

Currently if you check out the sources for GlueGen from CVS it’s zipped up in make/lib. We can check in the sources; could you contact me via email at my dev.java.net address? We would need to get a signed contributor agreement from you (linked to from the JOGL home page) and preferably have you officially release it under the BSD license.