From 57a9cd37b911b471f4950db4889a662504d71010 Mon Sep 17 00:00:00 2001
From: Mike Hearn <michael.hearn@oracle.com>
Date: Fri, 19 Jan 2024 15:32:59 +0100
Subject: [PATCH] Espresso: fix JavaDoc build.

Without this change, `mx javadoc` doesn't work due to
warnings.
---
 .../truffle/espresso/jdwp/api/FieldRef.java   |  2 +-
 .../dispatch/SuppressJavaDocWarning.java      | 28 +++++++++++++++++++
 .../runtime/dispatch/package-info.java        |  6 +++-
 .../substitutions/Target_sun_misc_Unsafe.java |  4 +--
 4 files changed, 36 insertions(+), 4 deletions(-)
 create mode 100644 espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/runtime/dispatch/SuppressJavaDocWarning.java

diff --git a/espresso/src/com.oracle.truffle.espresso.jdwp/src/com/oracle/truffle/espresso/jdwp/api/FieldRef.java b/espresso/src/com.oracle.truffle.espresso.jdwp/src/com/oracle/truffle/espresso/jdwp/api/FieldRef.java
index 93635a42fb05..314334d72851 100644
--- a/espresso/src/com.oracle.truffle.espresso.jdwp/src/com/oracle/truffle/espresso/jdwp/api/FieldRef.java
+++ b/espresso/src/com.oracle.truffle.espresso.jdwp/src/com/oracle/truffle/espresso/jdwp/api/FieldRef.java
@@ -67,7 +67,7 @@ public interface FieldRef {
     /**
      * Returns the declaring class of the field.
      * 
-     * @return the {@KlassRef} which declared this field
+     * @return the {@link KlassRef} which declared this field
      */
     KlassRef getDeclaringKlass();
 
diff --git a/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/runtime/dispatch/SuppressJavaDocWarning.java b/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/runtime/dispatch/SuppressJavaDocWarning.java
new file mode 100644
index 000000000000..59aec727d03d
--- /dev/null
+++ b/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/runtime/dispatch/SuppressJavaDocWarning.java
@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package com.oracle.truffle.espresso.runtime.dispatch;
+
+class SuppressJavaDocWarning {
+    // Javadoc complains about empty packages with no way to suppress the warning.
+}
diff --git a/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/runtime/dispatch/package-info.java b/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/runtime/dispatch/package-info.java
index 98c84ce3889e..cf4e50a68124 100644
--- a/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/runtime/dispatch/package-info.java
+++ b/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/runtime/dispatch/package-info.java
@@ -20,7 +20,11 @@
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
-//TODO GR-43114 fix warnings
+
+/**
+ * Polyglot interop related classes.
+ */
+// TODO GR-43114 fix warnings
 @SuppressPackageWarnings({"truffle-inlining", "truffle-sharing", "truffle-neverdefault", "truffle-limit"})
 package com.oracle.truffle.espresso.runtime.dispatch;
 
diff --git a/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/substitutions/Target_sun_misc_Unsafe.java b/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/substitutions/Target_sun_misc_Unsafe.java
index 18589461aa31..cae961be4252 100644
--- a/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/substitutions/Target_sun_misc_Unsafe.java
+++ b/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/substitutions/Target_sun_misc_Unsafe.java
@@ -721,8 +721,8 @@ public static boolean tryMonitorEnter(@SuppressWarnings("unused") @JavaType(Unsa
      * assigns to the elements of the given <tt>loadavg</tt> array. The system imposes a maximum of
      * 3 samples, representing averages over the last 1, 5, and 15 minutes, respectively.
      *
-     * @params loadavg an array of double of size nelems
-     * @params nelems the number of samples to be retrieved and must be 1 to 3.
+     * @param loadavg an array of double of size nelems
+     * @param nelems the number of samples to be retrieved and must be 1 to 3.
      *
      * @return the number of samples actually retrieved; or -1 if the load average is unobtainable.
      */