From 218f245f9cfaf918a04d3a37540c8876aadf0e43 Mon Sep 17 00:00:00 2001
From: stephengold <sgold@sonic.net>
Date: Sat, 27 Apr 2024 22:40:14 -0700
Subject: [PATCH] library:  javadoc and comment

---
 .../collision/shapes/MeshCollisionShape.java      |  2 +-
 .../shapes/infos/BoundingValueHierarchy.java      | 15 ++++++++++++---
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/MinieLibrary/src/main/java/com/jme3/bullet/collision/shapes/MeshCollisionShape.java b/MinieLibrary/src/main/java/com/jme3/bullet/collision/shapes/MeshCollisionShape.java
index 13ea85ebf..6ac0f24fd 100644
--- a/MinieLibrary/src/main/java/com/jme3/bullet/collision/shapes/MeshCollisionShape.java
+++ b/MinieLibrary/src/main/java/com/jme3/bullet/collision/shapes/MeshCollisionShape.java
@@ -480,7 +480,7 @@ private void createShape() {
         setMargin(margin);
 
         assert !hasBvh(shapeId);
-        if (bvh == null) {
+        if (bvh == null) { // Create an untracked native object:
             this.bvh = new BoundingValueHierarchy(this);
         } else {
             long bvhId = bvh.nativeId();
diff --git a/MinieLibrary/src/main/java/com/jme3/bullet/collision/shapes/infos/BoundingValueHierarchy.java b/MinieLibrary/src/main/java/com/jme3/bullet/collision/shapes/infos/BoundingValueHierarchy.java
index 3a241d714..2f41a5784 100644
--- a/MinieLibrary/src/main/java/com/jme3/bullet/collision/shapes/infos/BoundingValueHierarchy.java
+++ b/MinieLibrary/src/main/java/com/jme3/bullet/collision/shapes/infos/BoundingValueHierarchy.java
@@ -75,8 +75,8 @@ protected BoundingValueHierarchy() {
     }
 
     /**
-     * Instantiate a reference to the hierarchy of the specified
-     * MeshCollisionShape. Used internally.
+     * Instantiate an (untracked) reference to the hierarchy of the specified
+     * {@code MeshCollisionShape}.
      *
      * @param meshShape the pre-existing shape (not null)
      */
@@ -89,7 +89,11 @@ public BoundingValueHierarchy(MeshCollisionShape meshShape) {
     }
 
     /**
-     * Instantiate a hierarchy from serialized bytes.
+     * Instantiate a (tracked) hierarchy from serialized bytes.
+     * <p>
+     * If the bytes weren't generated on the current {@code Platform} with the
+     * same floating-point precision, the results are undefined (likely a JVM
+     * crash).
      *
      * @param bytes the serialized bytes (not null, unaffected)
      */
@@ -115,6 +119,11 @@ public boolean isCompressed() {
 
     /**
      * Serialize this hierarchy to a byte array.
+     * <p>
+     * Serialization can be used to avoid re-generating the BVH of a
+     * `MeshCollisionShape` each time it is instantiated. The resulting bytes
+     * are specific to a particular `MeshCollisionShape`. They are also specific
+     * to the current {@code Platform} and floating-point precision.
      *
      * @return a new array containing serialized bytes (not null)
      */