currently, GL/GLU/GLUT docs are not detail enough. the fields don’t really say much about itself. each function says it an interface to C language function (except for ones that are wholely written in java). if javadoc tags were to placed in gluegen, will it extract those comments as description to the fields and functions? Does gluegen reads comments in the opengl headers and ignore them? I do think that C function name should link to an online description for it. just a thought.
I agree that the javadocs could use more detail. However it’s not clear what route to take. GlueGen could easily be extended to allow manual javadoc to be specified for the functions it wraps into Java methods. If we insert the entire OpenGL API docs into the javadoc then the HTML will be too large. We could put links to the online docs at opengl.org in each method’s javadoc, but unfortunately even those docs seem to be pretty far out of date; the core man pages haven’t been updated in a long time to reflect the changes associated with the newer extensions. Do you or anybody else have any suggestions about the best and lowest-cost way to improve the documentation?
the last thread i read from opengl.org was on something about a wiki to which a call to developers contribution can be open.i believe the contributors-moderators there are in mid-process when i last read. but i has been a long time since my visit. jsr231 were to do something like that, it should be in loop with opengl.org. well, i found a like to that thread: http://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=013895. but to be sure i that i haven’t misinformed meself, i’ll read it again to see if it has any bread. so, in term of low cost, community contribution is it, i reckon.
GL doc is huge, humungus! would hover-over for document details help? that is, just tabulate all GL fields and functions categorically and have a hover-over mouse event that pops up a document details. (the detail should include what functions associate with a particular field, vise versa.) as for updating the docs to reflect changes brought forth from extensions, i think that requires a lot of work or extension experts.
The GL/GLU/GLUT docs does have a lot of blank lines because the members/fields don’t have doc-comment/description which makes the pages unnecessarily long, and without meat. again just me thoughts. – ka-el
I think generating links to wiki-page would be a wonderful idea.