javadoc fixes

CHANGELOG.md

@@ -5,6 +5,8 @@
 - Make Java 9 the default.
 - remove deprecations for 0.6.0
 - Remove ccp4j
+- Look at DContactGeom pos3()/normal3()
+- dxOrthogonalizeR returns true unconditionally... verify with ODE!
 - Bug: Dropping first box on Heightfield is wrong.
   -> Cylinder is also often iffy, but that is the same in C++ -> e.g. 7. cylinder (java) or 11th (c++)!
 - What is the deal with DJoint PARAM vs PARAM_N?
@@ -32,6 +34,8 @@
 - Nothing?
 
 ## 0.5.0 (unreleased)
+- Improved Android compatibility
+  [#124](https://github.com/tzaeschke/ode4j/pull/124)
 - Improved Android compatibility
   [#123](https://github.com/tzaeschke/ode4j/pull/123)
 - Avoid garbage collection of DContact. This is now implemented without pooling but with reusing

core-cpp/src/main/java/org/ode4j/cpp/internal/ApiCppJoint.java

@@ -162,6 +162,7 @@ public static DBallJoint dJointCreateBall (DWorld w, DJointGroup g) {
 	 * @param w world
 	 * @param g set to 0 to allocate the joint normally.
 	 * If it is nonzero the joint is allocated in the given joint group.
+	 * @return joint
 	 */
 	//ODE_API
 	public static DDoubleBallJoint dJointCreateDBall (DWorld w, DJointGroup g) {
@@ -604,6 +605,8 @@ public static void dJointSetBallParam (DBallJoint j, int parameter, double value
 
 	/**
 	 * Set the target distance for the double ball joint.
+	 * @param j j
+	 * @param distance distance
 	 */
 	//ODE_API
 	public static void dJointSetDBallDistance (DDoubleBallJoint j, double distance) {
@@ -1557,6 +1560,8 @@ public static double dJointGetBallParam (DBallJoint j, int parameter) {
 
 	/**
 	 * Get the target distance from double ball joint.
+	 * @param j joint
+	 * @return distance
 	 */
 	//ODE_API
 	public static double dJointGetDBallDistance (DDoubleBallJoint j) {

core/src/main/java/org/ode4j/math/DMatrix3.java

@@ -197,6 +197,7 @@ public DMatrix3 set(double i, double j, double k, double l, double m,
 	 * the 4th, 8th and 12th field. This is useful when using padded arrays.
 	 * @param da Initialisztion matrix
 	 * @param da_ofs Reading offset
+	 * @return this.
 	 */
 	public DMatrix3 set12(double[] da, int da_ofs) {
 		System.arraycopy(da, da_ofs, v, 0, da.length);
@@ -249,6 +250,7 @@ public DMatrix3 scale(double scale) {
 	 * B or C are stored in standard column format.
 	 * @param B source B
 	 * @param C source C
+	 * @return this.
 	 */
 	public DMatrix3 dMultiply0 (final DMatrix3C B,
 			final DMatrix3C C) {
@@ -734,6 +736,7 @@ public int hashCode() {
 	/**
 	 * Make the matrix an identity matrix.
 	 * Same as setIdenity().
+	 * @return This matrix.
 	 */
 	public DMatrix3 eqIdentity() {
 		eqZero();
@@ -758,6 +761,7 @@ public DMatrix3 setIdentity() {
 	/**
 	 * Set the matrix to zero.
 	 * Same as setZero().
+	 * @return This matrix.
 	 */
 	public DMatrix3 eqZero() {
 		Arrays.fill(v, 0);
@@ -768,6 +772,7 @@ public DMatrix3 eqZero() {
 	/**
 	 * Set the matrix to zero.
 	 * Same as eqZero().
+	 * @return This matrix.
 	 */
 	public DMatrix3 setZero() {
 		eqZero();
@@ -1009,6 +1014,7 @@ public double get(int i, int j) {
 	 * @param i row
 	 * @param j column
 	 * @param a value at (i,j)
+	 * @return This matrix.
 	 */
 	public DMatrix3 set(int i, int j, double a) {
 		v[i*MAX_J + j] = a;

core/src/main/java/org/ode4j/math/DQuaternion.java

@@ -123,6 +123,7 @@ public int dim() {
 	/**
 	 * Sets w of [w, x, y, z].
 	 * @param w w
+	 * @return This quaternion.
 	 */
 	public DQuaternion set0(double w) {
 		this.w = w;
@@ -132,6 +133,7 @@ public DQuaternion set0(double w) {
 	/**
 	 * Sets x of [w, x, y, z].
 	 * @param x x
+	 * @return This quaternion.
 	 */
 	public DQuaternion set1(double x) {
 		this.x = x;
@@ -141,6 +143,7 @@ public DQuaternion set1(double x) {
 	/**
 	 * Sets y of [w, x, y, z].
 	 * @param y y
+	 * @return This quaternion.
 	 */
 	public DQuaternion set2(double y) {
 		this.y = y;
@@ -150,6 +153,7 @@ public DQuaternion set2(double y) {
 	/**
 	 * Sets z of [w, x, y, z].
 	 * @param z z
+	 * @return This quaternion.
 	 */
 	public DQuaternion set3(double z) {
 		this.z = z;
@@ -225,6 +229,7 @@ public final DQuaternion sum(DQuaternion q1, DQuaternion q2, double d2) {
 	 * Set a vector/matrix at position i to a specific value.
 	 * @param i position
 	 * @param d value
+	 * @return This quaternion.
 	 */
 	public final DQuaternion set(int i, double d) {
 		switch (i) {
@@ -327,6 +332,7 @@ public final boolean safeNormalize4 () {
 	 * all the components by 1/a[i]. then we can compute the length of `a' and
 	 * scale the components by 1/l. this has been verified to work with vectors
 	 * containing the smallest representable numbers.
+	 * @return This quaternion.
 	 */
 	public DQuaternion normalize() {
 		if (!safeNormalize4()) throw new IllegalStateException(

core/src/main/java/org/ode4j/math/DVector3.java

@@ -398,6 +398,7 @@ public final boolean safeNormalize () {
 	 * containing the smallest representable numbers.
 	 * <p>
 	 * This method throws an IllegalArgumentException if no normal can be determined.
+	 * @return This vector.
 	 */
 	public final DVector3 normalize() {
 		OdeMath.dNormalize3(this);
@@ -423,7 +424,7 @@ public final double distance(DVector3C a) {
 	 * v.equals(a).
 	 * @param a other vector
 	 * @param eps maximum allowed difference per value
-	 * @return quality
+	 * @return equality
 	 */
 	@Override
 	public final boolean isEq(DVector3C a, double eps) {
@@ -462,6 +463,7 @@ public final boolean isEq(DVector3C a) {
 
 	/**
 	 * Set this vector equal to abs(this).
+	 * @return This vector.
 	 */
 	public final DVector3 eqAbs() {
 		set0( Math.abs(get0()));
@@ -663,6 +665,7 @@ public final DVector3 addScaled(DVector3C v2, double d) {
 	 * Set this vector = b x c.
 	 * @param b b
 	 * @param c c
+	 * @return This vector.
 	 */
 	public final DVector3 eqCross(DVector3C b, DVector3C c) {
 		set0( b.get1()*c.get2() - b.get2()*c.get1() );
@@ -695,6 +698,7 @@ public final DVector3 cross(DVector3C b) {
 	 * </pre> 
 	 * @param m matrix m
 	 * @param v2 vector v
+	 * @return This vector.
 	 */
 	public final DVector3 eqProd(DMatrix3C m, DVector3C v2) {
 	    set0( m.get00()*v2.get0()+  m.get01()*v2.get1()+  m.get02()*v2.get2() );

core/src/main/java/org/ode4j/math/DVector6.java

@@ -250,6 +250,7 @@ public final boolean safeNormalize6 ()
 	 * all the components by 1/a[i]. then we can compute the length of `a' and
 	 * scale the components by 1/l. this has been verified to work with vectors
 	 * containing the smallest representable numbers.
+	 * @return This vector.
 	 */
 	public DVector6 normalize()	{
 		if (!safeNormalize6()) throw new IllegalStateException(

core/src/main/java/org/ode4j/ode/DContactGeom.java

@@ -60,13 +60,15 @@ public DContactGeom() {}
 
 	/**
 	 * pos[3] is assigned in several places but never ysed. This is a dummy functioon to track this fact.
+	 * @param d d
 	 */
 	public void pos3(double d) {
 		// nothing
 	}
 
 	/**
 	 * normal[3] is assigned in several places but never ysed. This is a dummy functioon to track this fact.
+	 * @param d d
 	 */
 	public void normal3(double d) {
 		// nothing

core/src/main/java/org/ode4j/ode/DDoubleBallJoint.java

@@ -77,6 +77,7 @@ public interface DDoubleBallJoint extends DJoint {
 
 	/**
 	 * Set the target distance for the double ball joint.
+	 * @param distance distance
 	 */
 	void setDistance(double distance);
 

core/src/main/java/org/ode4j/ode/DHinge2Joint.java

@@ -53,6 +53,8 @@ public interface DHinge2Joint extends DJoint {
 	 * <p>
 	 * At least one of the axes must be not NULL. If NULL is passed, the corresponding
 	 * axis retains its existing value.
+	 * @param axis1 axis 1
+	 * @param axis2 axis 2
 	 */
 	void setAxes(DVector3C axis1, DVector3C axis2);
 
@@ -62,6 +64,12 @@ public interface DHinge2Joint extends DJoint {
 	 * This can change both axes at once avoiding transitions via invalid states
 	 * while changing axes one by one and having the first changed axis coincide
 	 * with the other axis existing direction.
+	 * @param x1 x of axis 1
+	 * @param y1 y of axis 1
+	 * @param z1 z of axis 1
+	 * @param x2 x of axis 2
+	 * @param y2 y of axis 2
+	 * @param z2 z of axis 2
 	 */
 	void setAxes(double x1, double y1, double z1, double x2, double y2, double z2);
 

core/src/main/java/org/ode4j/ode/DTriMesh.java

@@ -137,6 +137,7 @@ private dMESHDATAUSE() {}
 	/**
 	 * Per triangle callback. Allows the user to say if he wants a collision with
 	 * a particular triangle.
+	 * @param Callback the callback function
 	 */
 	////typedef int dTriCallback(dGeom TriMesh, dGeom RefObject, int TriangleIndex);
 	//ODE_API
@@ -165,6 +166,7 @@ private dMESHDATAUSE() {}
 	 * Allows the user to say if a ray collides with a triangle on barycentric
 	 * coords. The user can for example sample a texture with alpha transparency
 	 * to determine if a collision should occur.
+	 * @param Callback the callback function
 	 */
 	////typedef int dTriRayCallback(dGeom TriMesh, dGeom Ray, int TriangleIndex, double u, double v);
 	//ODE_API
@@ -243,14 +245,18 @@ interface DTriTriMergeCallback {
 
 
 	/**
-	 * returns the TriMeshDataID
+	 * @return the TriMeshData instance
 	 */
 	//ODE_API
 	//DTriMeshData dGeomTriMeshGetTriMeshDataID(DTriMesh g);
 	DTriMeshData getTriMeshData();
 
 	/**
 	 * Gets a triangle.
+	 * @param Index triangle index
+	 * @param v0 output node 0
+	 * @param v1 output node 1
+	 * @param v2 output node 2
 	 */
 	//ODE_API
 	//void dGeomTriMeshGetTriangle(dGeom g, int Index, dVector3* v0, dVector3* v1, dVector3* v2) {
@@ -259,28 +265,32 @@ interface DTriTriMergeCallback {
 	/**
 	 * Gets the point on the requested triangle and the given barycentric
 	 * coordinates.
+	 * @param index triangle index
+	 * @param u u
+	 * @param v v
+	 * @param Out output
 	 */
 	//ODE_API
 	//void dGeomTriMeshGetPoint(dGeomID g, int index, dReal u, dReal v, dVector3 Out)
 	void getPoint(int index, double u, double v, DVector3 Out);
 
-//	/*
-//
-//This is how the strided data works:
-//
-//struct StridedVertex{
-//	dVector3 Vertex;
-//	// Userdata
-//};
-//int VertexStride = sizeof(StridedVertex);
-//
-//struct StridedTri{
-//	int Indices[3];
-//	// Userdata
-//};
-//int TriStride = sizeof(StridedTri);
-//
-//	 */
+	//	/*
+	//
+	//This is how the strided data works:
+	//
+	//struct StridedVertex{
+	//	dVector3 Vertex;
+	//	// Userdata
+	//};
+	//int VertexStride = sizeof(StridedVertex);
+	//
+	//struct StridedTri{
+	//	int Indices[3];
+	//	// Userdata
+	//};
+	//int TriStride = sizeof(StridedTri);
+	//
+	//	 */
 
 	//ODE_API
 	int getTriangleCount ();

core/src/main/java/org/ode4j/ode/OdeHelper.java

@@ -691,16 +691,19 @@ public static DCapsule createCapsule(DSpace space, double radius, double length)
 	 * @param polygons An array of indices to the points of each polygon, it should be the
 	 * 	 number of vertices followed by that amount of indices to "points" in
 	 * 	 counter clockwise order
+	 * @return new DConvex instance
 	 */
 	public static DConvex createConvex(double[] planes, double[] points, int[] polygons) {
 		return DxConvex.dCreateConvex(null, planes, points, polygons);
 	}
 	/**
+	 * @param space the space instance
 	 * @param planes An array of planes in the form: normal X, normal Y, normal Z,Distance
 	 * @param points An array of points X,Y,Z
 	 * @param polygons An array of indices to the points of each polygon, it should be the
 	 * 	 number of vertices followed by that amount of indices to "points" in
 	 * 	 counter clockwise order
+	 * @return new DConvex instance
 	 */
 	public static DConvex createConvex(DSpace space, double[] planes, double[] points, int[] polygons) {
 		return DxConvex.dCreateConvex((DxSpace)space, planes, points, polygons);
@@ -714,19 +717,22 @@ public static DConvex createConvex(DSpace space, double[] planes, double[] point
 	 * @param polygons An array of indices to the points of each polygon, it should be the
 	 * 	 number of vertices followed by that amount of indices to "points" in
 	 * 	 counter clockwise order
+	 * @return new DConvex instance
 	 */
 	public static DConvex createConvex(double[] planes,
 									   int planeCount, double[] points, int pointCount, int[] polygons) {
 		return DxConvex.dCreateConvex(null, planes, planeCount, points, pointCount, polygons);
 	}
 	/**
+	 * @param space The space instance
 	 * @param planes An array of planes in the form: normal X, normal Y, normal Z,Distance
 	 * @param planeCount Amount of planes in `planes`
 	 * @param points An array of points X,Y,Z
 	 * @param pointCount Amount of points in `points`
 	 * @param polygons An array of indices to the points of each polygon, it should be the
 	 * 	 number of vertices followed by that amount of indices to "points" in
 	 * 	 counter clockwise order
+	 * @return new DConvex instance
 	 */
 	public static DConvex createConvex(DSpace space, double[] planes,
 									   int planeCount, double[] points, int pointCount, int[] polygons) {
@@ -1139,7 +1145,7 @@ public static DTriMesh createTriMesh(DSpace space, DTriMeshData data) {
 	 * @param data user data
 	 * @param callback callback (can be NULL)
 	 *                 NOTE: The callback is only called for Box, Capsule, Ray, Sphere and TriMesh. See issue #76.
-	 * // @param arrayCallback array callback (can be NULL) --> Not supported in GIMPACT.
+	 * // @param arrayCallback array callback (can be NULL) ---- Not supported in GIMPACT.
 	 * @param rayCallback ray callback (can be NULL)
 	 * @return trimesh
 	 */
@@ -1155,7 +1161,7 @@ public static DTriMesh createTriMesh(DSpace space, DTriMeshData data, DTriCallba
 	 * @param data user data
 	 * @param callback callback (can be NULL)
 	 *                 NOTE: The callback is only called for Box, Capsule, Ray, Sphere and TriMesh. See issue #76.
-	 * @param arrayCallback array callback (can be NULL) --> Not supported in GIMPACT.
+	 * @param arrayCallback array callback (can be NULL) ---- Not supported in GIMPACT.
 	 * @param rayCallback ray callback (can be NULL)
 	 * @return trimesh
 	 */