search

JOML-CI / JOML

A Java math library for OpenGL rendering calculations
MIT License
729 stars 104 forks source link

Missing Javadoc in Quaterniond #256

Closed lukehutch closed 4 years ago

lukehutch commented 4 years ago

Quaterniond is missing documentation on a bunch of methods. (I didn't check other classes to see if they are also missing documentation, e.g. Quaternionf.)

I noticed this because I couldn't remember if Quaterniond.transform(Vector3d) implements P[i+1] = Q P[i] Q' or P[i+1] = Q' P[i] Q, and was hoping the Javadoc would tell me.

httpdigest commented 4 years ago

All methods in Quaterniond have JavaDocs (either inherited from Quaterniondc or in Quaterniond itself) and your IDE should handle this (showing inherited JavaDocs for interface implementation methods). I agree that the documentation of some methods are not specific enough, like your mentioned Quaterniond.transform(Vector3d).

httpdigest commented 4 years ago

So, if you like, we could reword this issue to: "Quaterniondc.transform(Vector3d) does not tell about multiplication order" (or something like that).

lukehutch commented 4 years ago

I think the reason I'm not seeing any Javadoc whatsoever for some of these methods (in Eclipse) is that the methods are missing @Override.

https://github.com/JOML-CI/JOML/blob/master/src/org/joml/Quaterniond.java#L850

In old versions of Java (1.6 and older?), @Override couldn't be used for methods implemented from an interface. In newer versions, @Override is not only allowable of implemented interface methods, but I believe it's recommended (e.g. Eclipse will add this annotation automatically when you use a quick fix to add unimplemented methods from an interface), since it gives the programmer a heads-up that these methods either implement an interface or override a superclass method.

httpdigest commented 4 years ago

I don't see any issue with Eclipse (or IntelliJ IDEA or NetBeans) in regards to showing the JavaDoc of inherited methods without the inheriting method having a @Override annotation on the method. The JavaDoc of the interface method declaration shows just fine when I write the method call on the implementing class type. I don't think that needing to up the source level to 1.5 or having that annotation on implementing/overriding methods was ever needed for the inherited JavaDoc to show through. Here is what it looks in Eclipse for me

lukehutch commented 4 years ago

Thanks for verifying. I must have a setting somewhere for inherited Javadoc that is switched off.

lukehutch commented 4 years ago

I closed the bug -- although I agree with your comment that "Quaterniondc.transform(Vector3d) does not tell about multiplication order". Probably transformInverse also needs this Javadoc improvement. See also my new comment on (closed bug) #199 re. conjugateByInverse.