Documentation

OpenGL Development JOGL Development
#1

Hi All.

I’m new to JOGL and I want to open a bit of a discussion about the JavaDocs. I know that it relates directly to the OpenGL specification, as JOGL as I understand it is a direct link to the OpenGL API…?. The thing I wanted to discuss is that fact the JavaDocs that are available (at least the ones Ive found) just say what the relative OpenGL function is and offers no - be it simple - outline of what that function does! The consequence is that JOGL - from an inexperienced OpenGL programmers perspective - is very confusing at first, and this simple factor is partially to blame. Even basic pointers would vastly improve the documentation for all and strengthen JOGL as a practical usable API. Ive been programming Java for years and still always have to refer to documentation, as there’s a lot of it and if I could remember it all… Well I would need a big head. But having a specification description that just tells you what to look up in another specification seems, well a little daft.

I know that an adaption would take some time and effort as many of the classes and functions are not likely to change unless the underlying OpenGL functions change but I wanted to know what others thought? Should their be some sort of project to improve the JavaDocs? Are people already on it? I would assist but I don’t know OpenGL well enough to implement it, although if its directly related it wouldn’t be such a task! Is there better documentation Ive not found? Do you think it would be a pointless / unnecessary effort?

Any comments and thoughts would be highly appreciated!
Martin.

#2

Hello invisiblemartin!

strange that I can still see you :wink:

GL methods which are mapped directly to OpenGL functions have normally a link in the javadoc to the official OpenGL spec. Here is a example of glUniform:
http://www.opengl.org/sdk/docs/man/xhtml/glUniform.xml

I tried in past to render the pages directly in the auto completion javadoc window of netbeans but the java html renderer had some problems with this xml files… My second attempt was to inline the OpenGL doc into the javadoc but the generated html file was so large that firefox required around 1minute to load the page from hard disc ;D (IE crashed…)

I was somewhat surprised as I saw that NetBeans was still able to use the doc for autocompletion purposes but the XML problem remains.

So if you have a good method to convert the xml files to plain html (it contains some equations and special symbols) let me know.

#3

I COMPLETELY agree…just today I was tearing out my hair and swearing left and right because I could not figure out the damn array order for using glMultMatrixd() in JOGL…stupid little things like this are frustrating as heck.

#4

Yeah I know I’m not as invisible as I feel some times… ;D

Thanks for the link was very helpful. With regard to the JavaDocs, I’m was more suggesting the removal of the “Entry point (through function pointer) to C language function:” notes and replacing them with a short description as well as a link to the C spec. Some of the documentation is already like this in places but the nitty gritty one java.media.opengl.GL would benefit greatly from at least a brief one sentence description of what functions actually do. This wouldn’t have that much more impact on loading than it currently does (which already takes a while to load on my machine).

PS : XML > HTML, I know a few ways either by XLST or DOM access. Although using them within a dynamic live environment on large XML files may greatly reduce performance and combining the JOGL spec and C OpenGL spec would be enormous task. Actually a Java help style app may be the best way to do this… Ill look into it.

Martin.

#5

this is easily possible just experiment with the ant task in the JOGL build which generates the “Entry point…” sentence with the link.

But as I already said, adding a few lines per GL method is enough to generate huge html files… remember how many functions GL has (I already tried that).

you only have to convert the doc once at build time… its a ant task. If you would be able to inline the spec into the doc and maintain readability (independent of the html file size) this would be pretty cool since this could be used inside IDEs and the old dock for browsers.

I will see if I can find the modified ant tasks when I am back at home (in two days) but the inlining and tag cleanup was actually pretty strait forward.

[edit] RFE link for reference: https://jogl.dev.java.net/issues/show_bug.cgi?id=321

#6

The JOGL javadoc is generated with links to the C version of the function when available using a taglet I wrote some time ago (https://jogl.dev.java.net/source/browse/gluegen/src/java/net/highteq/nativetaglet/NativeTaglet.java?rev=1.1&view=markup). This taglet is configured via a properties-file (https://jogl.dev.java.net/source/browse/jogl/make/native-taglet.properties?rev=1.2&view=markup). It should also be quite easy to let the taglet read the xml and insert e.g. the first line of the function description directly into the javadoc. The more interesting functions however might not be this easily extracted since they are probably burried in some extension documentation at the opengl extension registry…