resolve javadoc warnings in the jme3-jbullet library (#1522)

* jme3-jbullet: resolve javadoc warnings

* jme3-jbullet/build.gradle: enable doclint

jme3-bullet/src/common/java/com/jme3/bullet/control/BetterCharacterControl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -514,6 +514,8 @@ public class BetterCharacterControl extends AbstractPhysicsControl implements Ph
     /**
      * This checks if the character can go from ducked to unducked state by
      * doing a ray test.
+     * 
+     * @return true if able to unduck, otherwise false
      */
     protected boolean checkCanUnDuck() {
         TempVars vars = TempVars.get();

jme3-bullet/src/common/java/com/jme3/bullet/control/CharacterControl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -76,7 +76,9 @@ public class CharacterControl extends PhysicsCharacter implements PhysicsControl
     /**
      * When set to true, the physics coordinates will be applied to the local
      * translation of the Spatial
-     * @param applyPhysicsLocal
+     *
+     * @param applyPhysicsLocal true→match local coordinates,
+     * false→match world coordinates (default=false)
      */
     public void setApplyPhysicsLocal(boolean applyPhysicsLocal) {
         applyLocal = applyPhysicsLocal;

jme3-bullet/src/common/java/com/jme3/bullet/util/CollisionShapeFactory.java

@@ -298,7 +298,9 @@ public class CollisionShapeFactory {
 
     /**
      * This method moves each child shape of a compound shape by the given vector
-     * @param vector
+     *
+     * @param compoundShape the shape to modify (not null)
+     * @param vector the offset vector (not null, unaffected)
      */
     public static void shiftCompoundShapeContents(CompoundCollisionShape compoundShape, Vector3f vector) {
         for (Iterator<ChildCollisionShape> it = new LinkedList<>(compoundShape.getChildren()).iterator(); it.hasNext();) {

jme3-jbullet/build.gradle

@@ -18,10 +18,3 @@ dependencies {
     compile project(':jme3-core')
     compile project(':jme3-terrain')
 }
-
-javadoc {
-    // Disable doclint for JDK8+.
-    if (JavaVersion.current().isJava8Compatible()){
-        options.addStringOption('Xdoclint:none', '-quiet')
-    }
-}

jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java

@@ -192,7 +192,8 @@ public class PhysicsSpace {
 
     /**
      * Used internally
-     * @param space
+     *
+     * @param space which space to simulate on the current thread
      */
     public static void setLocalThreadPhysicsSpace(PhysicsSpace space) {
         physicsSpaceTL.set(space);
@@ -381,7 +382,8 @@ public class PhysicsSpace {
     /**
      * updates the physics space, uses maxSteps<br>
      * @param time the current time value
-     * @param maxSteps
+     * @param maxSteps the maximum number of steps of size accuracy (&ge;1) or 0
+     * for a single step of size timeInterval
      */
     public void update(float time, int maxSteps) {
         if (getDynamicsWorld() == null) {
@@ -413,8 +415,9 @@ public class PhysicsSpace {
 
     /**
      * calls the callable on the next physics tick (ensuring e.g. force applying)
-     * @param <V>
-     * @param callable
+     *
+     * @param <V> the return type of the Callable
+     * @param callable the Callable to invoke
      * @return a new AppTask
      */
     public <V> Future<V> enqueue(Callable<V> callable) {
@@ -682,7 +685,9 @@ public class PhysicsSpace {
 
     /**
      * Sets the gravity of the PhysicsSpace, set before adding physics objects!
-     * @param gravity
+     *
+     * @param gravity the desired acceleration vector
+     * (in physics-space coordinates, not null, unaffected, default=0,-10,0)
      */
     public void setGravity(Vector3f gravity) {
         dynamicsWorld.setGravity(Converter.convert(gravity));
@@ -690,7 +695,10 @@ public class PhysicsSpace {
 
     /**
      * Gets the gravity of the PhysicsSpace
-     * @param gravity
+     *
+     * @param gravity storage for the result (modified if not null)
+     * @return the acceleration vector (in physics-space coordinates, either
+     * gravity or a new instance)
      */
     public Vector3f getGravity(Vector3f gravity) {
         javax.vecmath.Vector3f tempVec = new javax.vecmath.Vector3f();
@@ -716,7 +724,8 @@ public class PhysicsSpace {
      * Adds the specified listener to the physics tick listeners.
      * The listeners are called on each physics step, which is not necessarily
      * each frame but is determined by the accuracy of the physics space.
-     * @param listener
+     *
+     * @param listener the listener to register (not null, alias created)
      */
     public void addTickListener(PhysicsTickListener listener) {
         tickListeners.add(listener);
@@ -745,8 +754,10 @@ public class PhysicsSpace {
     /**
      * Adds a listener for a specific collision group, such a listener can disable collisions when they happen.<br>
      * There can be only one listener per collision group.
-     * @param listener
-     * @param collisionGroup
+     *
+     * @param listener the listener to register (not null, alias created)
+     * @param collisionGroup which group it should listen for (bitmask with
+     * exactly one bit set)
      */
     public void addCollisionGroupListener(PhysicsCollisionGroupListener listener, int collisionGroup) {
         collisionGroupListeners.put(collisionGroup, listener);
@@ -758,6 +769,12 @@ public class PhysicsSpace {
 
     /**
      * Performs a ray collision test and returns the results as a list of PhysicsRayTestResults
+     *
+     * @param from the starting location (physics-space coordinates, not null,
+     * unaffected)
+     * @param to the ending location (in physics-space coordinates, not null,
+     * unaffected)
+     * @return a new list of results (not null)
      */
     public List<PhysicsRayTestResult> rayTest(Vector3f from, Vector3f to) {
         List<PhysicsRayTestResult> results = new LinkedList<>();
@@ -767,6 +784,13 @@ public class PhysicsSpace {
 
     /**
      * Performs a ray collision test and returns the results as a list of PhysicsRayTestResults
+     *
+     * @param from the starting location (in physics-space coordinates, not
+     * null, unaffected)
+     * @param to the ending location (in physics-space coordinates, not null,
+     * unaffected)
+     * @param results the list to hold results (not null, modified)
+     * @return results
      */
     public List<PhysicsRayTestResult> rayTest(Vector3f from, Vector3f to, List<PhysicsRayTestResult> results) {
         results.clear();
@@ -794,6 +818,11 @@ public class PhysicsSpace {
      * Performs a sweep collision test and returns the results as a list of PhysicsSweepTestResults<br>
      * You have to use different Transforms for start and end (at least distance greater than 0.4f).
      * SweepTest will not see a collision if it starts INSIDE an object and is moving AWAY from its center.
+     *
+     * @param shape the shape to sweep (not null, convex, unaffected)
+     * @param start the starting physics-space transform (not null, unaffected)
+     * @param end the ending physics-space transform (not null, unaffected)
+     * @return a new list of results
      */
     public List<PhysicsSweepTestResult> sweepTest(CollisionShape shape, Transform start, Transform end) {
         List<PhysicsSweepTestResult> results = new LinkedList<>();
@@ -810,6 +839,12 @@ public class PhysicsSpace {
      * Performs a sweep collision test and returns the results as a list of PhysicsSweepTestResults<br>
      * You have to use different Transforms for start and end (at least distance greater than 0.4f).
      * SweepTest will not see a collision if it starts INSIDE an object and is moving AWAY from its center.
+     * 
+     * @param shape the shape to sweep (not null, convex, unaffected)
+     * @param start the starting physics-space transform (not null, unaffected)
+     * @param end the ending physics-space transform (not null, unaffected)
+     * @param results the list to hold results (not null, modified)
+     * @return results
      */
     public List<PhysicsSweepTestResult> sweepTest(CollisionShape shape, Transform start, Transform end, List<PhysicsSweepTestResult> results) {
         results.clear();
@@ -886,7 +921,8 @@ public class PhysicsSpace {
 
     /**
      * sets the accuracy of the physics computation, default=1/60s<br>
-     * @param accuracy
+     *
+     * @param accuracy the desired time step (in seconds, default=1/60)
      */
     public void setAccuracy(float accuracy) {
         this.accuracy = accuracy;
@@ -898,7 +934,9 @@ public class PhysicsSpace {
 
     /**
      * only applies for AXIS_SWEEP broadphase
-     * @param worldMin
+     *
+     * @param worldMin the desired minimum coordinates values (not null,
+     * unaffected, default=-10k,-10k,-10k)
      */
     public void setWorldMin(Vector3f worldMin) {
         this.worldMin.set(worldMin);
@@ -910,7 +948,9 @@ public class PhysicsSpace {
 
     /**
      * only applies for AXIS_SWEEP broadphase
-     * @param worldMax
+     *
+     * @param worldMax the desired maximum coordinates values (not null,
+     * unaffected, default=10k,10k,10k)
      */
     public void setWorldMax(Vector3f worldMax) {
         this.worldMax.set(worldMax);

jme3-jbullet/src/main/java/com/jme3/bullet/collision/PhysicsCollisionEvent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2012 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -74,6 +74,11 @@ public class PhysicsCollisionEvent extends EventObject {
 
     /**
      * used by event factory, called when event reused
+     *
+     * @param type the desired type
+     * @param source the desired first object (alias created)
+     * @param nodeB the desired 2nd object (alias created)
+     * @param cp the desired manifold (alias created)
      */
     public void refactor(int type, PhysicsCollisionObject source, PhysicsCollisionObject nodeB, ManifoldPoint cp) {
         this.source = source;

jme3-jbullet/src/main/java/com/jme3/bullet/collision/PhysicsCollisionObject.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2019 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -105,7 +105,8 @@ public abstract class PhysicsCollisionObject implements Savable {
      * Add a group that this object will collide with.<br>
      * Two object will collide when <b>one</b> of the parties has the
      * collisionGroup of the other in its collideWithGroups set.<br>
-     * @param collisionGroup
+     *
+     * @param collisionGroup the groups to add, ORed together (bitmask)
      */
     public void addCollideWithGroup(int collisionGroup) {
         this.collisionGroupsMask = this.collisionGroupsMask | collisionGroup;
@@ -113,7 +114,8 @@ public abstract class PhysicsCollisionObject implements Savable {
 
     /**
      * Remove a group from the list this object collides with.
-     * @param collisionGroup
+     *
+     * @param collisionGroup the groups to remove, ORed together (bitmask)
      */
     public void removeCollideWithGroup(int collisionGroup) {
         this.collisionGroupsMask = this.collisionGroupsMask & ~collisionGroup;
@@ -121,7 +123,9 @@ public abstract class PhysicsCollisionObject implements Savable {
 
     /**
      * Directly set the bitmask for collision groups that this object collides with.
-     * @param collisionGroups
+     *
+     * @param collisionGroups the desired groups, ORed together (bitmask,
+     * default=COLLISION_GROUP_01)
      */
     public void setCollideWithGroups(int collisionGroups) {
         this.collisionGroupsMask = collisionGroups;

jme3-jbullet/src/main/java/com/jme3/bullet/collision/shapes/CapsuleCollisionShape.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -68,9 +68,11 @@ public class CapsuleCollisionShape extends CollisionShape{
 
     /**
      * Creates a capsule shape around the given axis (0=X,1=Y,2=Z).
-     * @param radius
-     * @param height
-     * @param axis
+     *
+     * @param radius the desired unscaled radius
+     * @param height the desired unscaled height of the cylindrical portion
+     * @param axis which local axis for the height: 0→X, 1→Y,
+     * 2→Z
      */
     public CapsuleCollisionShape(float radius, float height, int axis) {
         this.radius=radius;

jme3-jbullet/src/main/java/com/jme3/bullet/collision/shapes/CollisionShape.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -61,6 +61,9 @@ public abstract class CollisionShape implements Savable {
 
     /**
      * used internally, not safe
+     * 
+     * @param mass the desired mass for the body
+     * @param vector storage for the result (not null, modified)
      */
     public void calculateLocalInertia(float mass, javax.vecmath.Vector3f vector) {
         if (cShape == null) {
@@ -75,6 +78,8 @@ public abstract class CollisionShape implements Savable {
 
     /**
      * used internally
+     *
+     * @return the pre-existing instance
      */
     public com.bulletphysics.collision.shapes.CollisionShape getCShape() {
         return cShape;
@@ -82,6 +87,8 @@ public abstract class CollisionShape implements Savable {
 
     /**
      * used internally
+     *
+     * @param cShape the shape to use (alias created)
      */
     public void setCShape(com.bulletphysics.collision.shapes.CollisionShape cShape) {
         this.cShape = cShape;

jme3-jbullet/src/main/java/com/jme3/bullet/collision/shapes/CompoundCollisionShape.java

@@ -77,6 +77,8 @@ public class CompoundCollisionShape extends CollisionShape {
      * adds a child shape at the given local translation
      * @param shape the child shape to add
      * @param location the local location of the child shape
+     * @param rotation the local orientation of the child shape (not null,
+     * unaffected)
      */
     public void addChildShape(CollisionShape shape, Vector3f location, Matrix3f rotation) {
         if(shape instanceof CompoundCollisionShape){

jme3-jbullet/src/main/java/com/jme3/bullet/collision/shapes/GImpactCollisionShape.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -81,6 +81,8 @@ public class GImpactCollisionShape extends CollisionShape{
 
     /**
      * creates a jme mesh from the collision shape, only needed for debugging
+     *
+     * @return a new Mesh
      */
     public Mesh createJmeMesh(){
         return Converter.convert(bulletMesh);

jme3-jbullet/src/main/java/com/jme3/bullet/collision/shapes/MeshCollisionShape.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -91,6 +91,8 @@ public class MeshCollisionShape extends CollisionShape {
 
     /**
      * creates a jme mesh from the collision shape, only needed for debugging
+     *
+     * @return a new Mesh
      */
     public Mesh createJmeMesh(){
         return Converter.convert(bulletMesh);

jme3-jbullet/src/main/java/com/jme3/bullet/collision/shapes/SphereCollisionShape.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -52,7 +52,8 @@ public class SphereCollisionShape extends CollisionShape {
 
     /**
      * creates a SphereCollisionShape with the given radius
-     * @param radius
+     *
+     * @param radius the desired radius (in unscaled units)
      */
     public SphereCollisionShape(float radius) {
         this.radius = radius;

jme3-jbullet/src/main/java/com/jme3/bullet/joints/ConeJoint.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2019 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -62,6 +62,8 @@ public class ConeJoint extends PhysicsJoint {
     }
 
     /**
+     * @param nodeA the body for the A end (not null, alias created)
+     * @param nodeB the body for the B end (not null, alias created)
      * @param pivotA local translation of the joint connection point in node A
      * @param pivotB local translation of the joint connection point in node B
      */
@@ -73,8 +75,14 @@ public class ConeJoint extends PhysicsJoint {
     }
 
     /**
+     * @param nodeA the body for the A end (not null, alias created)
+     * @param nodeB the body for the B end (not null, alias created)
      * @param pivotA local translation of the joint connection point in node A
      * @param pivotB local translation of the joint connection point in node B
+     * @param rotA the joint orientation in A's local coordinates (rotation
+     * matrix, alias created)
+     * @param rotB the joint orientation in B's local coordinates (rotation
+     * matrix, alias created)
      */
     public ConeJoint(PhysicsRigidBody nodeA, PhysicsRigidBody nodeB, Vector3f pivotA, Vector3f pivotB, Matrix3f rotA, Matrix3f rotB) {
         super(nodeA, nodeB, pivotA, pivotB);

jme3-jbullet/src/main/java/com/jme3/bullet/joints/HingeJoint.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -63,8 +63,15 @@ public class HingeJoint extends PhysicsJoint {
 
     /**
      * Creates a new HingeJoint
+     *
+     * @param nodeA the body for the A end (not null, alias created)
+     * @param nodeB the body for the B end (not null, alias created)
      * @param pivotA local translation of the joint connection point in node A
      * @param pivotB local translation of the joint connection point in node B
+     * @param axisA the joint axis in A's local coordinates (unit vector,
+     * alias created)
+     * @param axisB the joint axis in B's local coordinates (unit vector,
+     * alias created)
      */
     public HingeJoint(PhysicsRigidBody nodeA, PhysicsRigidBody nodeB, Vector3f pivotA, Vector3f pivotB, Vector3f axisA, Vector3f axisB) {
         super(nodeA, nodeB, pivotA, pivotB);

jme3-jbullet/src/main/java/com/jme3/bullet/joints/PhysicsJoint.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -54,6 +54,8 @@ public abstract class PhysicsJoint implements Savable {
     }
 
     /**
+     * @param nodeA the body for the A end (not null, alias created)
+     * @param nodeB the body for the B end (not null, alias created)
      * @param pivotA local translation of the joint connection point in node A
      * @param pivotB local translation of the joint connection point in node B
      */

jme3-jbullet/src/main/java/com/jme3/bullet/joints/Point2PointJoint.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2019 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -54,6 +54,8 @@ public class Point2PointJoint extends PhysicsJoint {
     }
 
     /**
+     * @param nodeA the body for the A end (not null, alias created)
+     * @param nodeB the body for the B end (not null, alias created)
      * @param pivotA local translation of the joint connection point in node A
      * @param pivotB local translation of the joint connection point in node B
      */

jme3-jbullet/src/main/java/com/jme3/bullet/joints/SixDofJoint.java

@@ -72,8 +72,15 @@ public class SixDofJoint extends PhysicsJoint {
     }
 
     /**
+     * @param nodeA the body for the A end (not null, alias created)
+     * @param nodeB the body for the B end (not null, alias created)
      * @param pivotA local translation of the joint connection point in node A
      * @param pivotB local translation of the joint connection point in node B
+     * @param rotA the joint orientation in A's local coordinates (rotation
+     * matrix, unaffected)
+     * @param rotB the joint orientation in B's local coordinates (rotation
+     * matrix, unaffected)
+     * @param useLinearReferenceFrameA true→use body A, false→use body
      */
     public SixDofJoint(PhysicsRigidBody nodeA, PhysicsRigidBody nodeB, Vector3f pivotA, Vector3f pivotB, Matrix3f rotA, Matrix3f rotB, boolean useLinearReferenceFrameA) {
         super(nodeA, nodeB, pivotA, pivotB);
@@ -92,8 +99,12 @@ public class SixDofJoint extends PhysicsJoint {
     }
 
     /**
+     * @param nodeA the body for the A end (not null, alias created)
+     * @param nodeB the body for the B end (not null, alias created)
      * @param pivotA local translation of the joint connection point in node A
      * @param pivotB local translation of the joint connection point in node B
+     * @param useLinearReferenceFrameA true→use body A, false→use body
+     * B
      */
     public SixDofJoint(PhysicsRigidBody nodeA, PhysicsRigidBody nodeB, Vector3f pivotA, Vector3f pivotB, boolean useLinearReferenceFrameA) {
         super(nodeA, nodeB, pivotA, pivotB);

jme3-jbullet/src/main/java/com/jme3/bullet/joints/SliderJoint.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2019 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -56,8 +56,16 @@ public class SliderJoint extends PhysicsJoint {
     }
 
     /**
+     * @param nodeA the body for the A end (not null, alias created)
+     * @param nodeB the body for the B end (not null, alias created)
      * @param pivotA local translation of the joint connection point in node A
      * @param pivotB local translation of the joint connection point in node B
+     * @param rotA the joint orientation in A's local coordinates (not null,
+     * alias unaffected)
+     * @param rotB the joint orientation in B's local coordinates (not null,
+     * alias unaffected)
+     * @param useLinearReferenceFrameA true→use body A, false→use body
+     * B
      */
     public SliderJoint(PhysicsRigidBody nodeA, PhysicsRigidBody nodeB, Vector3f pivotA, Vector3f pivotB, Matrix3f rotA, Matrix3f rotB, boolean useLinearReferenceFrameA) {
         super(nodeA, nodeB, pivotA, pivotB);
@@ -68,8 +76,12 @@ public class SliderJoint extends PhysicsJoint {
     }
 
     /**
+     * @param nodeA the body for the A end (not null, alias created)
+     * @param nodeB the body for the B end (not null, alias created)
      * @param pivotA local translation of the joint connection point in node A
      * @param pivotB local translation of the joint connection point in node B
+     * @param useLinearReferenceFrameA true→use body A, false→use body
+     * B
      */
     public SliderJoint(PhysicsRigidBody nodeA, PhysicsRigidBody nodeB, Vector3f pivotA, Vector3f pivotB, boolean useLinearReferenceFrameA) {
         super(nodeA, nodeB, pivotA, pivotB);

jme3-jbullet/src/main/java/com/jme3/bullet/objects/PhysicsCharacter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2019 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -97,7 +97,8 @@ public class PhysicsCharacter extends PhysicsCollisionObject {
 
     /**
      * Sets the location of this physics character
-     * @param location
+     *
+     * @param location the desired physics location (not null, unaffected)
      */
     public void warp(Vector3f location) {
         character.warp(Converter.convert(location, tempVec));
@@ -219,6 +220,7 @@ public class PhysicsCharacter extends PhysicsCollisionObject {
     }
 
     /**
+     * @param trans storage for the result (modified if not null)
      * @return the physicsLocation
      */
     public Vector3f getPhysicsLocation(Vector3f trans) {
@@ -261,6 +263,8 @@ public class PhysicsCharacter extends PhysicsCollisionObject {
 
     /**
      * used internally
+     *
+     * @return the pre-existing object
      */
     public KinematicCharacterController getControllerId() {
         return character;
@@ -268,6 +272,8 @@ public class PhysicsCharacter extends PhysicsCollisionObject {
 
     /**
      * used internally
+     *
+     * @return the pre-existing object
      */
     public PairCachingGhostObject getObjectId() {
         return gObject;

jme3-jbullet/src/main/java/com/jme3/bullet/objects/PhysicsGhostObject.java

@@ -138,6 +138,7 @@ public class PhysicsGhostObject extends PhysicsCollisionObject {
     }
 
     /**
+     * @param trans storage for the result (modified if not null)
      * @return the physicsLocation
      */
     public Vector3f getPhysicsLocation(Vector3f trans) {
@@ -150,6 +151,7 @@ public class PhysicsGhostObject extends PhysicsCollisionObject {
     }
 
     /**
+     * @param rot storage for the result (modified if not null)
      * @return the physicsLocation
      */
     public Quaternion getPhysicsRotation(Quaternion rot) {
@@ -162,6 +164,7 @@ public class PhysicsGhostObject extends PhysicsCollisionObject {
     }
 
     /**
+     * @param rot storage for the result (modified if not null)
      * @return the physicsLocation
      */
     public Matrix3f getPhysicsRotationMatrix(Matrix3f rot) {
@@ -199,6 +202,8 @@ public class PhysicsGhostObject extends PhysicsCollisionObject {
 
     /**
      * used internally
+     * 
+     * @return the pre-existing instance
      */
     public PairCachingGhostObject getObjectId() {
         return gObject;

jme3-jbullet/src/main/java/com/jme3/bullet/objects/PhysicsRigidBody.java

@@ -77,7 +77,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
 
     /**
      * Creates a new PhysicsRigidBody with the supplied collision shape
-     * @param shape
+     *
+     * @param shape the desired shape (not null, alias created)
      */
     public PhysicsRigidBody(CollisionShape shape) {
         collisionShape = shape;
@@ -175,6 +176,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
 
     /**
      * Gets the physics object location, instantiates a new Vector3f object
+     * 
+     * @return a new location vector (in physics-space coordinates, not null)
      */
     public Vector3f getPhysicsLocation() {
         return getPhysicsLocation(null);
@@ -182,6 +185,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
 
     /**
      * Gets the physics object rotation
+     *
+     * @return a new rotation matrix (in physics-space coordinates, not null)
      */
     public Matrix3f getPhysicsRotationMatrix() {
         return getPhysicsRotationMatrix(null);
@@ -190,6 +195,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Gets the physics object location, no object instantiation
      * @param location the location of the actual physics object is stored in this Vector3f
+     * @return a location vector (in physics-space coordinates, either
+     * location or a new vector)
      */
     public Vector3f getPhysicsLocation(Vector3f location) {
         if (location == null) {
@@ -202,6 +209,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Gets the physics object rotation as a matrix, no conversions and no object instantiation
      * @param rotation the rotation of the actual physics object is stored in this Matrix3f
+     * @return a rotation matrix (in physics-space coordinates, either
+     * rotation or a new matrix)
      */
     public Matrix3f getPhysicsRotationMatrix(Matrix3f rotation) {
         if (rotation == null) {
@@ -214,6 +223,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Gets the physics object rotation as a quaternion, converts the bullet Matrix3f value,
      * instantiates new object
+     *
+     * @return a new rotation Quaternion (in physics-space coordinates)
      */
     public Quaternion getPhysicsRotation(){
         return getPhysicsRotation(null);
@@ -222,6 +233,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Gets the physics object rotation as a quaternion, converts the bullet Matrix3f value
      * @param rotation the rotation of the actual physics object is stored in this Quaternion
+     * @return a rotation Quaternion (in physics-space coordinates, either
+     * rotation or a new instance)
      */
     public Quaternion getPhysicsRotation(Quaternion rotation){
         if (rotation == null) {
@@ -234,6 +247,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Gets the physics object location
      * @param location the location of the actual physics object is stored in this Vector3f
+     * @return a location vector (in physics-space coordinates, either
+     * location or a new vector)
      */
     public Vector3f getInterpolatedPhysicsLocation(Vector3f location) {
         if (location == null) {
@@ -246,6 +261,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Gets the physics object rotation
      * @param rotation the rotation of the actual physics object is stored in this Matrix3f
+     * @return a rotation matrix (in physics-space coordinates, either
+     * rotation or a new matrix)
      */
     public Matrix3f getInterpolatedPhysicsRotation(Matrix3f rotation) {
         if (rotation == null) {
@@ -259,7 +276,9 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
      * Sets the node to kinematic mode. in this mode the node is not affected by physics
      * but affects other physics objects. Its kinetic force is calculated by the amount
      * of movement it is exposed to and its weight.
-     * @param kinematic
+     *
+     * @param kinematic true→set kinematic mode, false→set dynamic
+     * (default=false)
      */
     public void setKinematic(boolean kinematic) {
         this.kinematic = kinematic;
@@ -310,7 +329,9 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     /**
      * Sets the amount of motion that has to happen in one physics tick to trigger the continuous motion detection<br>
      * This avoids the problem of fast objects moving through other objects, set to zero to disable (default)
-     * @param threshold
+     *
+     * @param threshold the desired minimum distance per timestep to trigger CCD
+     * (in physics-space units, &gt;0) or zero to disable CCD (default=0)
      */
     public void setCcdMotionThreshold(float threshold) {
         rBody.setCcdMotionThreshold(threshold);
@@ -334,7 +355,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
 
     /**
      * Sets the mass of this PhysicsRigidBody, objects with mass=0 are static.
-     * @param mass
+     *
+     * @param mass the desired mass (&gt;0) or 0 for a static body (default=1)
      */
     public void setMass(float mass) {
         this.mass = mass;
@@ -419,7 +441,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
 
     /**
      * The "bouncyness" of the PhysicsRigidBody, best performance if restitution=0
-     * @param restitution
+     *
+     * @param restitution the desired value (default=0)
      */
     public void setRestitution(float restitution) {
         constructionInfo.restitution = restitution;
@@ -524,7 +547,9 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
 
     /**
      * Apply a torque impulse to the PhysicsRigidBody in the next physics update.
-     * @param vec
+     *
+     * @param vec the torque impulse vector (in physics-space coordinates,
+     * not null, unaffected)
      */
     public void applyTorqueImpulse(final Vector3f vec) {
         rBody.applyTorqueImpulse(Converter.convert(vec, tempVec));
@@ -605,6 +630,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
 
     /**
      * do not use manually, joints are added automatically
+     *
+     * @param joint the joint to add (not null, alias created)
      */
     public void addJoint(PhysicsJoint joint) {
         if (!joints.contains(joint)) {
@@ -613,7 +640,7 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
     }
 
     /**
-     * 
+     * @param joint the joint to remove (not null, unaffected)
      */
     public void removeJoint(PhysicsJoint joint) {
         joints.remove(joint);
@@ -630,6 +657,8 @@ public class PhysicsRigidBody extends PhysicsCollisionObject {
 
     /**
      * used internally
+     * 
+     * @return the pre-existing object
      */
     public RigidBody getObjectId() {
         return rBody;

jme3-jbullet/src/main/java/com/jme3/bullet/objects/PhysicsVehicle.java

@@ -116,6 +116,8 @@ public class PhysicsVehicle extends PhysicsRigidBody {
 
     /**
      * Used internally, creates the actual vehicle constraint when vehicle is added to phyicsspace
+     * 
+     * @param space the PhysicsSpace to use (alias created) or null for none
      */
     public void createVehicle(PhysicsSpace space) {
         physicsSpace = space;
@@ -180,7 +182,8 @@ public class PhysicsVehicle extends PhysicsRigidBody {
 
     /**
      * This rebuilds the vehicle as there is no way in bullet to remove a wheel.
-     * @param wheel
+     *
+     * @param wheel the index of the wheel to remove (≥0, <count)
      */
     public void removeWheel(int wheel) {
         wheels.remove(wheel);
@@ -223,8 +226,10 @@ public class PhysicsVehicle extends PhysicsRigidBody {
      * The coefficient of friction between the tyre and the ground.
      * Should be about 0.8 for realistic cars, but can increased for better handling.
      * Set large (10000.0) for kart racers
-     * @param wheel
-     * @param frictionSlip
+     *
+     * @param wheel the index of the wheel to modify (≥0, <count)
+     * @param frictionSlip the desired coefficient of friction between tyre and
+     * ground (0.8→realistic car, 10000→kart racer, default=10.5)
      */
     public void setFrictionSlip(int wheel, float frictionSlip) {
         wheels.get(wheel).setFrictionSlip(frictionSlip);
@@ -235,6 +240,10 @@ public class PhysicsVehicle extends PhysicsRigidBody {
      * This is a bit of a hack, but it's quite effective. 0.0 = no roll, 1.0 = physical behaviour.
      * If m_frictionSlip is too high, you'll need to reduce this to stop the vehicle rolling over.
      * You should also try lowering the vehicle's centre of mass
+     *
+     * @param wheel the index of the wheel to modify (≥0, <count)
+     * @param rollInfluence the desired roll-influence factor (0→no roll
+     * torque, 1→realistic behavior, default=1)
      */
     public void setRollInfluence(int wheel, float rollInfluence) {
         wheels.get(wheel).setRollInfluence(rollInfluence);
@@ -259,8 +268,11 @@ public class PhysicsVehicle extends PhysicsRigidBody {
 
     /**
      * The maximum distance the suspension can be compressed (centimetres)
-     * @param wheel
-     * @param maxSuspensionTravelCm
+     *
+     * @param wheel the index of the wheel to modify (≥0, <count)
+     * @param maxSuspensionTravelCm the desired maximum amount a suspension can
+     * be compressed or expanded, relative to its rest length (in hundredths of
+     * a physics-space unit, default=500)
      */
     public void setMaxSuspensionTravelCm(int wheel, float maxSuspensionTravelCm) {
         wheels.get(wheel).setMaxSuspensionTravelCm(maxSuspensionTravelCm);
@@ -273,7 +285,9 @@ public class PhysicsVehicle extends PhysicsRigidBody {
     /**
      * This value caps the maximum suspension force, raise this above the default 6000 if your suspension cannot
      * handle the weight of your vehicle.
-     * @param maxSuspensionForce
+     *
+     * @param maxSuspensionForce the desired maximum force per wheel
+     * (default=6000)
      */
     public void setMaxSuspensionForce(float maxSuspensionForce) {
         tuning.maxSuspensionForce = maxSuspensionForce;
@@ -282,8 +296,10 @@ public class PhysicsVehicle extends PhysicsRigidBody {
     /**
      * This value caps the maximum suspension force, raise this above the default 6000 if your suspension cannot
      * handle the weight of your vehicle.
-     * @param wheel
-     * @param maxSuspensionForce
+     *
+     * @param wheel the index of the wheel to modify (≥0, <count)
+     * @param maxSuspensionForce the desired maximum force per wheel
+     * (default=6000)
      */
     public void setMaxSuspensionForce(int wheel, float maxSuspensionForce) {
         wheels.get(wheel).setMaxSuspensionForce(maxSuspensionForce);
@@ -314,8 +330,10 @@ public class PhysicsVehicle extends PhysicsRigidBody {
      * Set to k * 2.0 * FastMath.sqrt(m_suspensionStiffness) so k is proportional to critical damping.<br>
      * k = 0.0 undamped/bouncy, k = 1.0 critical damping<br>
      * 0.1 to 0.3 are good values
-     * @param wheel
-     * @param suspensionCompression
+     *
+     * @param wheel the index of the wheel to modify (&ge;0, &lt;count)
+     * @param suspensionCompression the desired damping coefficient
+     * (default=4.4)
      */
     public void setSuspensionCompression(int wheel, float suspensionCompression) {
         wheels.get(wheel).setWheelsDampingCompression(suspensionCompression);
@@ -342,8 +360,9 @@ public class PhysicsVehicle extends PhysicsRigidBody {
     /**
      * The damping coefficient for when the suspension is expanding.
      * See the comments for setSuspensionCompression for how to set k.
-     * @param wheel
-     * @param suspensionDamping
+     *
+     * @param wheel the index of the wheel to modify (&ge;0, &lt;count)
+     * @param suspensionDamping the desired damping coefficient (default=2.3)
      */
     public void setSuspensionDamping(int wheel, float suspensionDamping) {
         wheels.get(wheel).setWheelsDampingRelaxation(suspensionDamping);
@@ -360,7 +379,10 @@ public class PhysicsVehicle extends PhysicsRigidBody {
      * Use before adding wheels, this is the default used when adding wheels.
      * After adding the wheel, use direct wheel access.<br>
      * The stiffness constant for the suspension.  10.0 - Offroad buggy, 50.0 - Sports car, 200.0 - F1 Car
-     * @param suspensionStiffness 
+     *
+     * @param suspensionStiffness the desired stiffness coefficient
+     * (10&rarr;off-road buggy, 50&rarr;sports car, 200&rarr;Formula-1 race car,
+     * default=5.88)
      */
     public void setSuspensionStiffness(float suspensionStiffness) {
         tuning.suspensionStiffness = suspensionStiffness;
@@ -368,8 +390,11 @@ public class PhysicsVehicle extends PhysicsRigidBody {
 
     /**
      * The stiffness constant for the suspension.  10.0 - Offroad buggy, 50.0 - Sports car, 200.0 - F1 Car
-     * @param wheel
-     * @param suspensionStiffness
+     *
+     * @param wheel the index of the wheel to modify (&ge;0, &lt;count)
+     * @param suspensionStiffness the desired stiffness coefficient
+     * (10&rarr;off-road buggy, 50&rarr;sports car, 200&rarr;Formula-1 race car,
+     * default=5.88)
      */
     public void setSuspensionStiffness(int wheel, float suspensionStiffness) {
         wheels.get(wheel).setSuspensionStiffness(suspensionStiffness);
@@ -466,6 +491,8 @@ public class PhysicsVehicle extends PhysicsRigidBody {
 
     /**
      * used internally
+     * 
+     * @return the pre-existing instance
      */
     public RaycastVehicle getVehicleId() {
         return vehicle;

jme3-jbullet/src/main/java/com/jme3/bullet/objects/VehicleWheel.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2019 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -150,7 +150,10 @@ public class VehicleWheel implements Savable {
 
     /**
      * the stiffness constant for the suspension.  10.0 - Offroad buggy, 50.0 - Sports car, 200.0 - F1 Car
-     * @param suspensionStiffness
+     *
+     * @param suspensionStiffness the desired stiffness coefficient
+     * (10→off-road buggy, 50→sports car, 200→Formula-1 race car,
+     * default=20)
      */
     public void setSuspensionStiffness(float suspensionStiffness) {
         this.suspensionStiffness = suspensionStiffness;
@@ -164,7 +167,9 @@ public class VehicleWheel implements Savable {
     /**
      * the damping coefficient for when the suspension is expanding.
      * See the comments for setWheelsDampingCompression for how to set k.
-     * @param wheelsDampingRelaxation
+     *
+     * @param wheelsDampingRelaxation the desired damping coefficient
+     * (default=2.3)
      */
     public void setWheelsDampingRelaxation(float wheelsDampingRelaxation) {
         this.wheelsDampingRelaxation = wheelsDampingRelaxation;
@@ -180,7 +185,9 @@ public class VehicleWheel implements Savable {
      * Set to k * 2.0 * FastMath.sqrt(m_suspensionStiffness) so k is proportional to critical damping.<br>
      * k = 0.0 undamped/bouncy, k = 1.0 critical damping<br>
      * 0.1 to 0.3 are good values
-     * @param wheelsDampingCompression
+     *
+     * @param wheelsDampingCompression the desired damping coefficient
+     * (default=4.4)
      */
     public void setWheelsDampingCompression(float wheelsDampingCompression) {
         this.wheelsDampingCompression = wheelsDampingCompression;
@@ -195,7 +202,9 @@ public class VehicleWheel implements Savable {
      * the coefficient of friction between the tyre and the ground.
      * Should be about 0.8 for realistic cars, but can increased for better handling.
      * Set large (10000.0) for kart racers
-     * @param frictionSlip
+     *
+     * @param frictionSlip the desired coefficient of friction between tyre and
+     * ground (0.8&rarr;realistic car, 10000&rarr;kart racer, default=10.5)
      */
     public void setFrictionSlip(float frictionSlip) {
         this.frictionSlip = frictionSlip;
@@ -224,7 +233,10 @@ public class VehicleWheel implements Savable {
 
     /**
      * the maximum distance the suspension can be compressed (centimetres)
-     * @param maxSuspensionTravelCm
+     *
+     * @param maxSuspensionTravelCm the desired maximum amount the suspension
+     * can be compressed or expanded, relative to its rest length (in hundredths
+     * of a physics-space unit, default=500)
      */
     public void setMaxSuspensionTravelCm(float maxSuspensionTravelCm) {
         this.maxSuspensionTravelCm = maxSuspensionTravelCm;
@@ -238,7 +250,9 @@ public class VehicleWheel implements Savable {
     /**
      * The maximum suspension force, raise this above the default 6000 if your suspension cannot
      * handle the weight of your vehicle.
-     * @param maxSuspensionForce
+     *
+     * @param maxSuspensionForce the desired maximum force per wheel
+     * (default=6000)
      */
     public void setMaxSuspensionForce(float maxSuspensionForce) {
         this.maxSuspensionForce = maxSuspensionForce;
@@ -296,6 +310,9 @@ public class VehicleWheel implements Savable {
 
     /**
      * returns the location where the wheel collides with the ground (world space)
+     *
+     * @param vec storage for the result (not null, modified)
+     * @return a location vector (in physics-space coordinates)
      */
     public Vector3f getCollisionLocation(Vector3f vec) {
         Converter.convert(wheelInfo.raycastInfo.contactPointWS, vec);
@@ -304,6 +321,8 @@ public class VehicleWheel implements Savable {
 
     /**
      * returns the location where the wheel collides with the ground (world space)
+     *
+     * @return a new location vector (in physics-space coordinates)
      */
     public Vector3f getCollisionLocation() {
         return Converter.convert(wheelInfo.raycastInfo.contactPointWS);
@@ -311,6 +330,9 @@ public class VehicleWheel implements Savable {
 
     /**
      * returns the normal where the wheel collides with the ground (world space)
+     *
+     * @param vec storage for the result (not null, modified)
+     * @return a unit vector (in physics-space coordinates)
      */
     public Vector3f getCollisionNormal(Vector3f vec) {
         Converter.convert(wheelInfo.raycastInfo.contactNormalWS, vec);
@@ -319,6 +341,8 @@ public class VehicleWheel implements Savable {
 
     /**
      * returns the normal where the wheel collides with the ground (world space)
+     *
+     * @return a new unit vector (in physics-space coordinates)
      */
     public Vector3f getCollisionNormal() {
         return Converter.convert(wheelInfo.raycastInfo.contactNormalWS);
@@ -327,6 +351,9 @@ public class VehicleWheel implements Savable {
     /**
      * returns how much the wheel skids on the ground (for skid sounds/smoke etc.)<br>
      * 0.0 = wheels are sliding, 1.0 = wheels have traction.
+     *
+     * @return the relative amount of traction (0&rarr;wheel is sliding,
+     * 1&rarr;wheel has full traction)
      */
     public float getSkidInfo() {
         return wheelInfo.skidInfo;
@@ -335,6 +362,8 @@ public class VehicleWheel implements Savable {
     /**
      * returns how many degrees the wheel has turned since the last physics
      * step.
+     *
+     * @return the rotation angle (in radians)
      */
     public float getDeltaRotation() {
         return wheelInfo.deltaRotation;
@@ -403,7 +432,7 @@ public class VehicleWheel implements Savable {
     /**
     * write the content of the wheelWorldRotation into the store
     * 
-    * @param store
+    * @param store storage for the result (not null, modified)
     */
     public void getWheelWorldRotation(final Quaternion store) {
         store.set(this.wheelWorldRotation);
@@ -412,7 +441,7 @@ public class VehicleWheel implements Savable {
     /**
     * write the content of the wheelWorldLocation into the store
     * 
-    * @param store
+    * @param store storage for the result (not null, modified)
     */
     public void getWheelWorldLocation(final Vector3f store) {
         store.set(this.wheelWorldLocation);

jme3-jbullet/src/main/java/com/jme3/bullet/objects/infos/RigidBodyMotionState.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -79,7 +79,8 @@ public class RigidBodyMotionState extends MotionState {
 
     /**
      * called from bullet when the transform of the rigidbody changes
-     * @param worldTrans
+     *
+     * @param worldTrans the new value (not null, unaffected)
      */
     @Override
     public void setWorldTransform(Transform worldTrans) {
@@ -102,7 +103,9 @@ public class RigidBodyMotionState extends MotionState {
 
     /**
      * applies the current transform to the given jme Node if the location has been updated on the physics side
-     * @param spatial
+     *
+     * @param spatial where to apply the physics transform (not null, modified)
+     * @return true if changed
      */
     public boolean applyTransform(Spatial spatial) {
         if (!physicsLocationDirty) {

jme3-jbullet/src/main/java/com/jme3/bullet/util/DebugShapeFactory.java

@@ -73,7 +73,8 @@ public class DebugShapeFactory {
     /**
      * Creates a debug shape from the given collision shape. This is mostly used internally.<br>
      * To attach a debug shape to a physics object, call <code>attachDebugShape(AssetManager manager);</code> on it.
-     * @param collisionShape
+     *
+     * @param collisionShape the CollisionShape to use or null
      * @return a new Spatial or null
      */
     public static Spatial getDebugShape(CollisionShape collisionShape) {