docs: simplify verbose JavaDoc documentation

Reduce class-level documentation verbosity by ~70%:
- Focus on 'what' rather than detailed 'how' explanations
- Remove verbose @param/@return/@throws from methods
- Maintain essential information for API understanding

Author: anivar

rhino/src/main/java/org/mozilla/javascript/FinalizationQueue.java

@@ -13,12 +13,7 @@
 /**
  * Shared finalization queue infrastructure for FinalizationRegistry.
  *
- * <p>Provides a shared ReferenceQueue (for JVM efficiency per aardvark179's recommendation) and
- * polling mechanism during JavaScript execution. Each FinalizationRegistry manages its own state
- * while using this shared infrastructure for GC detection.
- *
- * <p>This design avoids the overhead of multiple ReferenceQueues while maintaining proper
- * separation of registry-specific logic.
+ * <p>Provides shared ReferenceQueue for JVM efficiency and GC detection polling.
  */
 public class FinalizationQueue {
 

rhino/src/main/java/org/mozilla/javascript/NativeFinalizationRegistry.java

@@ -15,24 +15,8 @@
 /**
  * Implementation of ECMAScript 2021 FinalizationRegistry.
  *
- * <p>FinalizationRegistry allows JavaScript code to register cleanup callbacks that are called when
- * objects are garbage collected. This implementation provides:
- *
- * <ul>
- *   <li>Self-contained design - each registry manages its own registrations
- *   <li>Shared ReferenceQueue for JVM efficiency (per aardvark179's recommendation)
- *   <li>Integration with Rhino's Context finalization infrastructure
- *   <li>Thread-safe registration/unregistration using concurrent data structures
- *   <li>Bounded cleanup processing to prevent performance issues
- * </ul>
- *
- * <p>Key methods:
- *
- * <ul>
- *   <li>{@code register(target, heldValue, unregisterToken)} - register object for cleanup
- *   <li>{@code unregister(token)} - remove registrations by token
- *   <li>{@code cleanupSome(callback)} - process pending cleanups synchronously
- * </ul>
+ * <p>Allows JavaScript code to register cleanup callbacks for garbage collected objects. Uses
+ * shared ReferenceQueue for efficiency and integrates with Rhino's Context system.
  *
  * @see <a href="https://tc39.es/ecma262/#sec-finalization-registry-objects">ECMAScript
  *     FinalizationRegistry</a>
@@ -59,14 +43,7 @@ public class NativeFinalizationRegistry extends ScriptableObject {
     /** Temporary callback override for cleanupSome() method */
     private volatile Function cleanupSomeCallback = null;
 
-    /**
-     * Initialize the FinalizationRegistry constructor and prototype in the given scope.
-     *
-     * @param cx the JavaScript context
-     * @param scope the scope to install FinalizationRegistry in
-     * @param sealed whether to seal the constructor and prototype
-     * @return the FinalizationRegistry constructor function
-     */
+    /** Initialize FinalizationRegistry constructor and prototype. */
     public static Object init(Context cx, Scriptable scope, boolean sealed) {
         LambdaConstructor constructor =
                 new LambdaConstructor(
@@ -120,24 +97,12 @@ public static Object init(Context cx, Scriptable scope, boolean sealed) {
         return constructor;
     }
 
-    /**
-     * Private constructor for FinalizationRegistry instances.
-     *
-     * @param cleanupCallback the function to call when objects are finalized
-     */
+    /** Private constructor for FinalizationRegistry instances. */
     private NativeFinalizationRegistry(Function cleanupCallback) {
         this.cleanupCallback = cleanupCallback;
     }
 
-    /**
-     * JavaScript constructor implementation.
-     *
-     * @param cx the JavaScript context
-     * @param scope the constructor scope
-     * @param args constructor arguments (first must be a function)
-     * @return new FinalizationRegistry instance
-     * @throws TypeError if callback is not a function
-     */
+    /** JavaScript constructor implementation. */
     private static NativeFinalizationRegistry jsConstructor(
             Context cx, Scriptable scope, Object[] args) {
         if (args.length < 1 || !(args[0] instanceof Function)) {
@@ -153,16 +118,7 @@ private static NativeFinalizationRegistry jsConstructor(
         return registry;
     }
 
-    /**
-     * JavaScript register() method implementation.
-     *
-     * @param cx the JavaScript context (unused but required by Rhino)
-     * @param scope the method scope (unused but required by Rhino)
-     * @param thisObj the 'this' object (must be FinalizationRegistry)
-     * @param args method arguments: target, heldValue, [unregisterToken]
-     * @return undefined
-     * @throws TypeError if arguments are invalid
-     */
+    /** JavaScript register() method implementation. */
     private static Object register(
             Context cx, Scriptable scope, Scriptable thisObj, Object[] args) {
         NativeFinalizationRegistry registry = realThis(thisObj, "register");
@@ -198,31 +154,14 @@ private static Object register(
         return Undefined.instance;
     }
 
-    /**
-     * JavaScript unregister() method implementation.
-     *
-     * @param cx the JavaScript context (unused but required by Rhino)
-     * @param scope the method scope (unused but required by Rhino)
-     * @param thisObj the 'this' object (must be FinalizationRegistry)
-     * @param args method arguments: unregisterToken
-     * @return boolean indicating whether any registrations were removed
-     */
+    /** JavaScript unregister() method implementation. */
     private static Object unregister(
             Context cx, Scriptable scope, Scriptable thisObj, Object[] args) {
         NativeFinalizationRegistry registry = realThis(thisObj, "unregister");
         return registry.unregisterToken(args);
     }
 
-    /**
-     * JavaScript cleanupSome() method implementation.
-     *
-     * @param cx the JavaScript context
-     * @param scope the method scope (unused but required by Rhino)
-     * @param thisObj the 'this' object (must be FinalizationRegistry)
-     * @param args method arguments: [callback]
-     * @return undefined
-     * @throws TypeError if callback is provided but not a function
-     */
+    /** JavaScript cleanupSome() method implementation. */
     private static Object cleanupSome(
             Context cx, Scriptable scope, Scriptable thisObj, Object[] args) {
         NativeFinalizationRegistry registry = realThis(thisObj, "cleanupSome");
@@ -411,17 +350,8 @@ private void processCleanups(Context cx, int maxCleanups) {
     /**
      * Clean up when this registry is being GC'd.
      *
-     * <p>Note: finalize() is deprecated in Java 9+ but is still the most appropriate mechanism for
-     * this use case. The newer Cleaner API is not suitable because:
-     *
-     * <ul>
-     *   <li>FinalizationRegistry needs dynamic registration/unregistration
-     *   <li>Cleaner requires static cleanup actions defined at object creation
-     *   <li>We need to clear references when the registry itself is collected
-     * </ul>
-     *
-     * <p>This is intentionally using finalize() as recommended by aardvark179 for this specific use
-     * case where we need to clean up when the registry itself is GC'd.
+     * <p>Uses finalize() over Cleaner API due to dynamic registration requirements. Recommended by
+     * aardvark179 for this specific GC cleanup use case.
      */
     @Override
     @SuppressWarnings({"deprecation", "finalize", "Finalize"})

rhino/src/main/java/org/mozilla/javascript/NativeWeakRef.java

@@ -11,25 +11,10 @@
 /**
  * Implementation of ECMAScript 2021 WeakRef.
  *
- * <p>WeakRef allows holding a weak reference to an object without preventing its garbage
- * collection. This is useful for caches, mappings, or any scenario where you want to reference an
- * object without keeping it alive.
- *
- * <p>Key features:
- *
- * <ul>
- *   <li>Weak reference semantics - target can be garbage collected
- *   <li>Single {@code deref()} method to access target if still alive
- *   <li>Returns undefined if target has been collected
- *   <li>Thread-safe access using standard Java WeakReference
- *   <li>Coordinates with FinalizationRegistry for consistent GC behavior
- * </ul>
- *
- * <p>Unlike FinalizationRegistry which reacts to object finalization, WeakRef simply provides a way
- * to check if an object is still reachable without keeping it alive.
+ * <p>Allows holding weak references to objects without preventing garbage collection. Provides
+ * {@code deref()} method to access target if still alive.
  *
  * @see <a href="https://tc39.es/ecma262/#sec-weak-ref-objects">ECMAScript WeakRef Objects</a>
- * @see NativeFinalizationRegistry
  */
 public class NativeWeakRef extends ScriptableObject {
     private static final long serialVersionUID = 1L;
@@ -41,14 +26,7 @@ public class NativeWeakRef extends ScriptableObject {
     /** The weak reference to the target object */
     private WeakReference<Object> weakReference;
 
-    /**
-     * Initialize the WeakRef constructor and prototype in the given scope.
-     *
-     * @param cx the JavaScript context
-     * @param scope the scope to install WeakRef in
-     * @param sealed whether to seal the constructor and prototype
-     * @return the WeakRef constructor function
-     */
+    /** Initialize WeakRef constructor and prototype. */
     static Object init(Context cx, Scriptable scope, boolean sealed) {
         LambdaConstructor constructor =
                 new LambdaConstructor(
@@ -81,15 +59,7 @@ static Object init(Context cx, Scriptable scope, boolean sealed) {
         return constructor;
     }
 
-    /**
-     * JavaScript constructor implementation.
-     *
-     * @param cx the JavaScript context
-     * @param scope the constructor scope
-     * @param args constructor arguments (first must be an object)
-     * @return new WeakRef instance
-     * @throws TypeError if target is not an object
-     */
+    /** JavaScript constructor implementation. */
     private static Scriptable jsConstructor(Context cx, Scriptable scope, Object[] args) {
         if (args.length < 1) {
             throw ScriptRuntime.typeErrorById(
@@ -121,14 +91,7 @@ private static boolean isValidTarget(Object target) {
         return ScriptRuntime.isObject(target);
     }
 
-    /**
-     * Validate and cast 'this' object to WeakRef.
-     *
-     * @param thisObj the 'this' object from JavaScript call
-     * @param name method name for error messages
-     * @return validated WeakRef instance
-     * @throws TypeError if thisObj is not a proper WeakRef
-     */
+    /** Validate and cast 'this' object to WeakRef. */
     private static NativeWeakRef realThis(Scriptable thisObj, String name) {
         if (!(thisObj instanceof NativeWeakRef)) {
             throw ScriptRuntime.typeErrorById("msg.incompat.call", CLASS_NAME + '.' + name);