Posted by Sven Gothel on Feb 27, 2011; 1:57pm
URL: https://forum.jogamp.org/Am-i-being-helpful-or-am-I-being-rude-tp2585969p2588334.html

On Sunday, February 27, 2011 03:30:06 bardackx [via jogamp] wrote:
>
> First than anything, I want to aclear up that my mother language isn´t
> english, so I am not completely shure about the use of helpful in the title
> (the word I was looking for is the translation of "acomedido" (is a person
> that offers his help always he can be helpful) ) with that said, I proceed.

All good - yes your help (everything) is appreciated.

Many of us here are no native English speakers either :)

>
> I have noticed that many (many) methods form the GLn objects have for
> javadoc something like
>
> "Interface to C language function: GLuint glCreateProgram(void);"
>
> Is this deliverated?
It is deliberately generated, yes.

>
> If it is, then please accept my apologies, if it is not, then I want to help
> and fill the javadoc for those interface functions with theit respective
> counterpart on the
> http://www.opengl.org/sdk/docs/man4/xhtml/glCreateShader.xml OpenGL
> Reference Pages,  (the link may be redundant).

..

On Sunday, February 27, 2011 13:58:11 Michael Bien [via jogamp] wrote:
> the methods should contain a link to the reference page of the gl
> function. We had once an option to inline the reference pages in the
> javadoc, but some browsers weren't able to open the huge javadoc page
> back than :)

That should work and partially does:

http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GL2ES2.html

http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GL2ES2.html#glGetProgramInfoLog%28int,%20int,%20java.nio.IntBuffer,%20java.nio.ByteBuffer%29

Some methods don't have a link to the GL xhtml site,
due to either aliasing of the method name (ie removing ARB/EXT - subsumed stuff),
or it is our thing.

We also mention the sub spec in the doc, ie 'Part of GL_VERSION_2_0'.


Manually adding the whole doc is not desired, since it would be a source for bugs.
For the same reason we auto create all the binding methods (if possible).

Another reason is that we should be lazy, ie not doing this kind of redundant donkey work :)
Sure we have a lot other things to achieve, so feature contribution,
bug fixes or use cases (junit tests) are very welcome and very helpful.

One may also like to review generated methods the GL profile separation (GL2/GL3/GL2GL3 etc),
the code .. etc.

Bottom line - you and everybody is welcome providing information
while understanding the needs for constructive communication (eg FAQ about bug reports) :)
In the end .. it's 'us' - you too.

Cheers, Sven