Add a flag to disable parameter renames for parchment (needed for unobf)

README.md

@@ -60,11 +60,11 @@ Usage: jst [-hV] [--debug] [--in-format=<inputFormat>] [--libraries-list=<librar
            [--max-queue-depth=<maxQueueDepth>] [--out-format=<outputFormat>]
            [--problems-report=<problemsReport>] [--classpath=<addToClasspath>]...
            [--ignore-prefix=<ignoredPrefixes>]... [--enable-parchment
-           --parchment-mappings=<mappingsPath> [--[no-]parchment-javadoc]
-           [--parchment-conflict-prefix=<conflictPrefix>]] [--enable-accesstransformers
-           --access-transformer=<atFiles> [--access-transformer=<atFiles>]...
-           [--access-transformer-validation=<validation>]] [--enable-interface-injection
-           [--interface-injection-stubs=<stubOut>]
+           --parchment-mappings=<mappingsPath> [--[no-]parchment-javadoc] [--[no-]
+           parchment-parameters] [--parchment-conflict-prefix=<conflictPrefix>]]
+           [--enable-accesstransformers --access-transformer=<atFiles>
+           [--access-transformer=<atFiles>]... [--access-transformer-validation=<validation>]]
+           [--enable-interface-injection [--interface-injection-stubs=<stubOut>]
            [--interface-injection-marker=<annotationMarker>]
            [--interface-injection-data=<paths>]...] [--enable-unpick [--unpick-data=<paths>]...]
            INPUT OUTPUT
@@ -104,6 +104,8 @@ Plugin - parchment
                            Whether Parchment javadocs should be applied
       --parchment-mappings=<mappingsPath>
                            The location of the Parchment mappings file
+      --[no-]parchment-parameters
+                           Whether Parchment parameters should be applied
 Plugin - accesstransformers
       --access-transformer=<atFiles>
 

parchment/src/main/java/net/neoforged/jst/parchment/GatherReplacementsVisitor.java

@@ -23,13 +23,13 @@
 import java.util.IdentityHashMap;
 import java.util.List;
 import java.util.Map;
-import java.util.Objects;
 import java.util.Set;
 import java.util.function.UnaryOperator;
 
 class GatherReplacementsVisitor extends PsiRecursiveElementVisitor {
     private final NamesAndDocsDatabase namesAndDocs;
     private final boolean enableJavadoc;
+    private final boolean enableParameters;
     @Nullable
     private final UnaryOperator<String> conflictResolver;
     private final Replacements replacements;
@@ -47,10 +47,12 @@ class GatherReplacementsVisitor extends PsiRecursiveElementVisitor {
 
     public GatherReplacementsVisitor(NamesAndDocsDatabase namesAndDocs,
                                      boolean enableJavadoc,
+                                     boolean enableParameters,
                                      @Nullable UnaryOperator<String> conflictResolver,
                                      Replacements replacements) {
         this.namesAndDocs = namesAndDocs;
         this.enableJavadoc = enableJavadoc;
+        this.enableParameters = enableParameters;
         this.conflictResolver = conflictResolver;
         this.replacements = replacements;
     }
@@ -138,44 +140,49 @@ else if (PsiHelper.isNonStaticInnerClass(psiMethod.getContainingClass())) {
                     // implications for the field names.
                     if (paramData != null && paramData.getName() != null && !PsiHelper.isRecordConstructor(psiMethod)) {
                         var paramName = namer.apply(paramData.getName());
-
-                        // We cannot rename a parameter to name that was already taken in this scope
-                        if (activeNames.contains(paramName)) {
-                            // If we have no conflict resolver then we simply don't try to rename this parameter
-                            if (conflictResolver == null) {
-                                parameterOrder.add(psiParameter.getName());
-                                continue;
-                            }
-
-                            // Keep applying the conflict resolver until the name is no longer used
-                            while (activeNames.contains(paramName)) {
-                                paramName = conflictResolver.apply(paramName);
+                        if (enableParameters) {
+                            // We cannot rename a parameter to name that was already taken in this scope
+                            if (activeNames.contains(paramName)) {
+                                // If we have no conflict resolver then we simply don't try to rename this parameter
+                                if (conflictResolver == null) {
+                                    parameterOrder.add(psiParameter.getName());
+                                    continue;
+                                }
+
+                                // Keep applying the conflict resolver until the name is no longer used
+                                while (activeNames.contains(paramName)) {
+                                    paramName = conflictResolver.apply(paramName);
+                                }
                             }
-                        }
 
-                        // Replace parameters within the method body
-                        activeParameters.put(psiParameter, paramName);
-                        activeNames.add(paramName);
+                            // Replace parameters within the method body
+                            activeParameters.put(psiParameter, paramName);
+                            activeNames.add(paramName);
 
-                        // Find and replace the parameter identifier
-                        replacements.replace(psiParameter.getNameIdentifier(), paramName);
+                            // Find and replace the parameter identifier
+                            replacements.replace(psiParameter.getNameIdentifier(), paramName);
 
-                        // Record the replacement for remapping existing Javadoc @param tags
-                        renamedParameters.put(psiParameter.getName(), paramName);
+                            // Record the replacement for remapping existing Javadoc @param tags
+                            renamedParameters.put(psiParameter.getName(), paramName);
 
-                        hadReplacements = true;
+                            hadReplacements = true;
 
-                        parameterOrder.add(paramName);
+                            parameterOrder.add(paramName);
+                        } else {
+                            parameterOrder.add(psiParameter.getName());
+                        }
                     } else {
                         parameterOrder.add(psiParameter.getName());
                     }
 
                     // Optionally provide parameter javadocs
                     if (paramData != null && paramData.getJavadoc() != null) {
-                        parameterJavadoc.put(
-                                Objects.requireNonNullElse(paramData.getName(), psiParameter.getName()),
-                                paramData.getJavadoc()
-                        );
+                        // If parameter renaming is disabled, always use the source name
+                        if (enableParameters && paramData.getName() != null) {
+                            parameterJavadoc.put(paramData.getName(), paramData.getJavadoc());
+                        } else {
+                            parameterJavadoc.put(psiParameter.getName(), paramData.getJavadoc());
+                        }
                     }
                 }
 
@@ -207,7 +214,7 @@ else if (PsiHelper.isNonStaticInnerClass(psiMethod.getContainingClass())) {
                     return;
                 }
             }
-        } else if (element instanceof PsiReferenceExpression refExpr && refExpr.getReferenceNameElement() != null) {
+        } else if (enableParameters && element instanceof PsiReferenceExpression refExpr && refExpr.getReferenceNameElement() != null) {
             for (var entry : activeParameters.entrySet()) {
                 if (refExpr.isReferenceTo(entry.getKey())) {
                     replacements.replace(refExpr.getReferenceNameElement(), entry.getValue());

parchment/src/main/java/net/neoforged/jst/parchment/ParchmentTransformer.java

@@ -26,6 +26,14 @@ public class ParchmentTransformer implements SourceTransformer {
     )
     public boolean enableJavadoc = true;
 
+    @CommandLine.Option(
+            names = "--parchment-parameters",
+            description = "Whether Parchment parameter names should be applied",
+            negatable = true,
+            fallbackValue = "true"
+    )
+    public boolean enableParameters = true;
+
     @CommandLine.Option(names = "--parchment-conflict-prefix", description = "Apply the prefix specified if a Parchment parameter name conflicts with existing variable names")
     public String conflictPrefix;
 
@@ -56,7 +64,7 @@ public void beforeRun(TransformContext context) {
 
     @Override
     public void visitFile(PsiFile psiFile, Replacements replacements) {
-        var visitor = new GatherReplacementsVisitor(namesAndDocs, enableJavadoc, conflictResolver, replacements);
+        var visitor = new GatherReplacementsVisitor(namesAndDocs, enableJavadoc, enableParameters, conflictResolver, replacements);
         visitor.visitElement(psiFile);
     }
 

tests/data/parchment/javadoc-only/expected/ExistingJavadoc.java

@@ -0,0 +1,28 @@
+/**
+ * Existing class javadoc.
+ * <p>
+ * Parchment Class Line 1
+ * Parchment Class Line 2
+ * Parchment Class Line 3
+ */
+public class ExistingJavadoc {
+
+    /**
+     * Existing Javadoc, isn't it great?
+     * <p>
+     * Parchment Method Line 1
+     * Parchment Method Line 2
+     * Parchment Method Line 3
+     *
+     * @param x Parchment Parameter Documentation. Long oh so very long Lorem ipsum
+     *          dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet
+     * @param y Some description for x very long very long very long very long very
+     *          long very long very long very
+     * @param z Javadoc only, no rename
+     * @author SomeAuthor
+     * @return Some return value
+     */
+    int m(int x, int y, int z) {
+    }
+
+}

tests/data/parchment/javadoc-only/parchment.json

@@ -0,0 +1,39 @@
+{
+  "version": "1.1.0",
+  "classes": [
+    {
+      "name": "ExistingJavadoc",
+      "javadoc": [
+        "Parchment Class Line 1",
+        "Parchment Class Line 2",
+        "Parchment Class Line 3"
+      ],
+      "methods": [
+        {
+          "name": "m",
+          "descriptor": "(III)I",
+          "javadoc": [
+            "Parchment Method Line 1",
+            "Parchment Method Line 2",
+            "Parchment Method Line 3"
+          ],
+          "parameters": [
+            {
+              "index": 1,
+              "name": "newX",
+              "javadoc": "Parchment Parameter Documentation. Long oh so very long Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet"
+            },
+            {
+              "index": 2,
+              "name": "newY"
+            },
+            {
+              "index": 3,
+              "javadoc": "Javadoc only, no rename"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

tests/data/parchment/javadoc-only/source/ExistingJavadoc.java

@@ -0,0 +1,18 @@
+/**
+ * Existing class javadoc.
+ */
+public class ExistingJavadoc {
+
+    /**
+     * Existing Javadoc, isn't it great?
+     *
+     * @param y Some description for x very long very long very long very long
+     *          very long very long very long very
+     * @param x This will be overwritten
+     * @return Some return value
+     * @author       SomeAuthor
+     */
+    int m(int x, int y, int z) {
+    }
+
+}

tests/src/test/java/net/neoforged/jst/tests/EmbeddedTest.java

@@ -1,6 +1,5 @@
 package net.neoforged.jst.tests;
 
-import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
 import com.google.gson.TypeAdapter;
 import com.google.gson.stream.JsonReader;
@@ -236,6 +235,11 @@ void testAnonymousClasses() throws Exception {
         void testConflicts() throws Exception {
             runParchmentTest("conflicts", "mappings.tsrg", "--parchment-conflict-prefix=p_");
         }
+
+        @Test
+        void testJavadocOnly() throws Exception {
+            runParchmentTest("javadoc-only", "parchment.json", "--no-parchment-parameters");
+        }
     }
 
     @Nested