Enforce WrapFactory users to override new wrap(...) and wrapAsJavaObject(...) method

* move "main" comments to "main" method, add `@since`
* mark methods that should not be overridden as `final`

Author: ZZZank

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

@@ -19,12 +19,19 @@
  * and call {@link Context#setWrapFactory(WrapFactory)} Once an instance of this class or an
  * extension of this class is enabled for a given context (by calling setWrapFactory on that
  * context), Rhino will call the methods of this class whenever it needs to wrap a value resulting
- * from a call to a Java method or an access to a Java field.
+ * from calling a Java method or accessing a Java field.
  *
  * @see org.mozilla.javascript.Context#setWrapFactory(WrapFactory)
  * @since 1.5 Release 4
  */
 public class WrapFactory {
+    /**
+     * @see #wrap(Context, Scriptable, Object, TypeInfo)
+     */
+    public final Object wrap(Context cx, Scriptable scope, Object obj, Class<?> staticType) {
+        return wrap(cx, scope, obj, TypeInfoFactory.GLOBAL.create(staticType));
+    }
+
     /**
      * Wrap the object.
      *
@@ -42,14 +49,11 @@ public class WrapFactory {
      * @param cx the current Context for this thread
      * @param scope the scope of the executing script
      * @param obj the object to be wrapped. Note it can be null.
-     * @param staticType type hint. If security restrictions prevent to wrap object based on its
-     *     class, staticType will be used instead.
+     * @param staticType type hint. It will be used for improving generic support and fallback type
+     *     when security restrictions prevent wrapping object based on object class
      * @return the wrapped value.
+     * @since 1.9.0
      */
-    public Object wrap(Context cx, Scriptable scope, Object obj, Class<?> staticType) {
-        return wrap(cx, scope, obj, TypeInfoFactory.GLOBAL.create(staticType));
-    }
-
     public Object wrap(Context cx, Scriptable scope, Object obj, TypeInfo staticType) {
         if (obj == null || obj == Undefined.instance || obj instanceof Scriptable) {
             return obj;
@@ -95,6 +99,14 @@ public Scriptable wrapNewObject(Context cx, Scriptable scope, Object obj) {
         return wrapAsJavaObject(cx, scope, obj, TypeInfo.NONE);
     }
 
+    /**
+     * @see #wrapAsJavaObject(Context, Scriptable, Object, TypeInfo)
+     */
+    public final Scriptable wrapAsJavaObject(
+            Context cx, Scriptable scope, Object javaObject, Class<?> staticType) {
+        return wrapAsJavaObject(cx, scope, javaObject, TypeInfoFactory.GLOBAL.create(staticType));
+    }
+
     /**
      * Wrap Java object as Scriptable instance to allow full access to its methods and fields from
      * JavaScript.
@@ -108,15 +120,11 @@ public Scriptable wrapNewObject(Context cx, Scriptable scope, Object obj) {
      * @param cx the current Context for this thread
      * @param scope the scope of the executing script
      * @param javaObject the object to be wrapped
-     * @param staticType type hint. If security restrictions prevent to wrap object based on its
-     *     class, staticType will be used instead.
+     * @param staticType type hint. It will be used for improving generic support and fallback type
+     *     when security restrictions prevent wrapping object based on object class
      * @return the wrapped value which shall not be null
+     * @since 1.9.0
      */
-    public Scriptable wrapAsJavaObject(
-            Context cx, Scriptable scope, Object javaObject, Class<?> staticType) {
-        return wrapAsJavaObject(cx, scope, javaObject, TypeInfoFactory.GLOBAL.create(staticType));
-    }
-
     public Scriptable wrapAsJavaObject(
             Context cx, Scriptable scope, Object javaObject, TypeInfo staticType) {
         if (staticType.shouldReplace() && javaObject != null) {