diff --git a/README.md b/README.md index 62d68cc..606910a 100644 --- a/README.md +++ b/README.md @@ -60,11 +60,11 @@ Usage: jst [-hV] [--debug] [--in-format=] [--libraries-list=] [--out-format=] [--problems-report=] [--classpath=]... [--ignore-prefix=]... [--enable-parchment - --parchment-mappings= [--[no-]parchment-javadoc] - [--parchment-conflict-prefix=]] [--enable-accesstransformers - --access-transformer= [--access-transformer=]... - [--access-transformer-validation=]] [--enable-interface-injection - [--interface-injection-stubs=] + --parchment-mappings= [--[no-]parchment-javadoc] [--[no-] + parchment-parameters] [--parchment-conflict-prefix=]] + [--enable-accesstransformers --access-transformer= + [--access-transformer=]... [--access-transformer-validation=]] + [--enable-interface-injection [--interface-injection-stubs=] [--interface-injection-marker=] [--interface-injection-data=]...] [--enable-unpick [--unpick-data=]...] INPUT OUTPUT @@ -104,6 +104,8 @@ Plugin - parchment Whether Parchment javadocs should be applied --parchment-mappings= The location of the Parchment mappings file + --[no-]parchment-parameters + Whether Parchment parameters should be applied Plugin - accesstransformers --access-transformer= diff --git a/parchment/src/main/java/net/neoforged/jst/parchment/GatherReplacementsVisitor.java b/parchment/src/main/java/net/neoforged/jst/parchment/GatherReplacementsVisitor.java index 1d57043..e415827 100644 --- a/parchment/src/main/java/net/neoforged/jst/parchment/GatherReplacementsVisitor.java +++ b/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 conflictResolver; private final Replacements replacements; @@ -47,10 +47,12 @@ class GatherReplacementsVisitor extends PsiRecursiveElementVisitor { public GatherReplacementsVisitor(NamesAndDocsDatabase namesAndDocs, boolean enableJavadoc, + boolean enableParameters, @Nullable UnaryOperator 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()); diff --git a/parchment/src/main/java/net/neoforged/jst/parchment/ParchmentTransformer.java b/parchment/src/main/java/net/neoforged/jst/parchment/ParchmentTransformer.java index 9f7f233..13f6392 100644 --- a/parchment/src/main/java/net/neoforged/jst/parchment/ParchmentTransformer.java +++ b/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); } diff --git a/tests/data/parchment/javadoc-only/expected/ExistingJavadoc.java b/tests/data/parchment/javadoc-only/expected/ExistingJavadoc.java new file mode 100644 index 0000000..3230edd --- /dev/null +++ b/tests/data/parchment/javadoc-only/expected/ExistingJavadoc.java @@ -0,0 +1,28 @@ +/** + * Existing class javadoc. + *

+ * Parchment Class Line 1 + * Parchment Class Line 2 + * Parchment Class Line 3 + */ +public class ExistingJavadoc { + + /** + * Existing Javadoc, isn't it great? + *

+ * 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) { + } + +} diff --git a/tests/data/parchment/javadoc-only/parchment.json b/tests/data/parchment/javadoc-only/parchment.json new file mode 100644 index 0000000..6643251 --- /dev/null +++ b/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" + } + ] + } + ] + } + ] +} \ No newline at end of file diff --git a/tests/data/parchment/javadoc-only/source/ExistingJavadoc.java b/tests/data/parchment/javadoc-only/source/ExistingJavadoc.java new file mode 100644 index 0000000..fab0c34 --- /dev/null +++ b/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) { + } + +} diff --git a/tests/src/test/java/net/neoforged/jst/tests/EmbeddedTest.java b/tests/src/test/java/net/neoforged/jst/tests/EmbeddedTest.java index 3f195b8..be70f49 100644 --- a/tests/src/test/java/net/neoforged/jst/tests/EmbeddedTest.java +++ b/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