JOGL OpenGL reference WIKI started

OpenGL Development JOGL Development
#1

I have just started an OpenGL reference page for JOGL here: http://wiki.java.net/bin/view/Games/OpenGL-Reference

Please take your time and fill in documentation for one or two functions, if you have a java.net account (or register ;D). I tried to set a good example by copying the glAccum-documentation from the blue book and adapted it to the JOGL syntax. It took me less than half an hour, so it’s doable for everyone here ::slight_smile:

@Ken
I started this because of a comment in another thread regarding the GL javadoc. Maybe you could include the WIKI-Links in the generated javadoc, to make the WIKI the “official” java opengl documentation.

#2

He come on guys… half an hour… just one function :wink:

#3

I don’t really see the point, to be honest…

#4

One of the most complains I heard from new JOGL users are, that there is no javadoc available (Try a search for javadoc in the JOGL-forums). There was a short Thread regarding the possibility to include the OpenGL reference in the javadoc, which seems to be a no-go, since the doc is massive and the OpenGL-interface not split in several classes.

In the linked thread, the idea came up, just to link to an online-reference from inside the JOGL javadoc. To make this possible, I started the WIKI page. Maybe there is no point for an experienced user, but there surely is one for a newbe. Also several problems/confusion in usage arise from the different parameter syntax (regarding arrays and pointers for instance), that could be avoided by having a “real” JOGL OpenGL reference.

#5

online reference still isn’t javadoc - and from my POV it is a bit pointless

#6

Yes I know, but if it is not possible (or at least problematical) to add the reference to the javadoc itself, it seems better than nothing. It also should be possible to generate an offline-version of the reference and add it as seperate folder to the javadoc, so you only have to do one more click.

Once this state is reached, I plan to create a netbeans plugin to provide the entries in this reference instead of the javadoc for gl-calls, so there will be a complete online help available to develop JOGL applications.

Sorry, I don’t know the POV abbrevation… I assume it has nothing to do with POV ray and more with offline or something :wink:

#7

POV = Point of View
The opengl manual and reference is online - and offline (man pages, pdf) and has been so for ages.
Manually editing each man page to fit into JOGL’s version is pretty boring work. But if someone wants to do it - go for it…

#8

I like the wiki approach, but I think it’d be better suited to JOGL / General using OpenGL rather than the enumeration of the functions, which, as has been pointed out, is easy to find.

#9

I added the reference to the already existing JOGL wiki. I would be glad, if there would go more work in the overall content as well. The page could use better promotion as well, since nobody seems to notice it’s existence.

but only half an our of boring work… I only ask for conversion of one function.

It can be really useful once it is linked from the javadoc or is integrated as help in an IDE. I will work towards this… even if noone is willing to help :stuck_out_tongue:

ONE DAY THERE WILL BE JOGL ONLINE HELP AND YOU FEEL VERY SORRY FOR NOT BEING INVOLVED, BUT THIS DAY IT WILL BE TO LATE FOR YOU, ALL THE HONOUR WILL BE MINE… AND THE DAY AFTER I WILL HOLD SWAY OVER THE WORLD… MUAHAHAHAHA

sorry, couldn’t resit :wink:

#10

Isn’t it much, MUCH more efficient to write an automatic doc generator a la gluegen, but for docs?

It’d also be relatively future proof as you can just rerun it if anything changes.

#11

Not sure, but I have done such things in the past, and it nearly alway turned out, that the time needed to make a decent generator is double the time you need to just do it by hand. In most cases it also turned out, that a complete rerun was never needed as well. To be honest in most cases the reason to write a generator may be due to the less boring work, than just writing documentation. My employer gone mad at me because of this twice :wink:

If I just want to reference the existing documentation you might be right, but I aim for an accurate JOGL javadoc replacement and the documentation of the changed parameter syntax seems hard to be generated.

#12

ANTLR is a very useful tool for this kind of thing. I don’t think it would take terribly long, even if you had to write the gramar from the ground up.

#13

How could ANTLR help in this situation?

#14

Markus suggested “… an automatic doc generator a la gluegen …”, and I thought if you went that route, then ANTLR would probably be a good bet for parsing docs.

#15

Oh I see. Misunderstood you.

The problem is not to generate a parser for the JOGL-API to find the reference anchors, writing a doclet for the javadoc generator should be sufficient. “Glueing” the existing doc should also be a no-brainer, since it is already organized by function name. I could (more or less) easily generate the now missing WIKI content from the Blue Book reference online and convert it to the WIKI format and even upload it automatically using httpclient or something.

But that just don’t cut it. I would copy the Blue Book, which is already available. There is no way around manually editing the content in the reference to reflect the differences in between the C and JOGL syntax to create a accurate documentation. Thats were the WIKI comes in. I admit I have overestimated the longing for such a documentation (at least in respect to the people in this forum) and the willingness to contribute to it (which is ok), but I strongly believe in it’s necessity.

#16

If you see an obvious way to link to existing reference pages say on opengl.org from the autogenerated GlueGen javadoc, I would be more than happy to help modify GlueGen to autogenerate such links.

I’m personally concerned about the current state of the core documentation on opengl.org, though. As far as I can tell, a ton of extensions have been added since the most recent set of man pages were produced and so the manual pages are very far out-of-date, not indicating how certain core OpenGL routines are modified by various extensions. If I’m wrong about this, please correct me.

I think a worthwhile effort to do in this area would be to work with the community on opengl.org to revise the core on-line documentation for OpenGL. I have to agree with most of the other posters here that replicating it into a java-fied format isn’t the most productive use of time given the current doc situation.

#17

Accordingly to the documentation, the PyOpenGL Man Pages are generated automatically. So why don’t ask them, if you can (re-)use their code?

#18

That was one reason to go with a wiki, so errors could be corrected while filling in the content

Hmm, I have not much knowledge of the OpenGL community as a whole and am afraid trying to ignite an complete overhaul of the “official” OpenGL documentation might be a bit much to swollow for me.

I don’t think, modifying GlueGen will be necessary. I will try to prototype a doclet.

Thanks for the hint, I will look at it

#19

Hey all,
I’ve added a categoric table view of the functions (though not complete in meantime). Thought this would be more approachable since you get the overview. - Ka-El

#20

I do think that the GLueGen should, for the final static variables of GL/GLU, produce a group of tables for these variables in a categoric manner for javadoc. Because, as you know, the jsr231 javadoc is really large and it contains mostly empty spaces. So tables are great for this and link each state to the appropriate function. - Ka-El