Skip to content

feat: Add a only javadoc application mode to the parchment plugin #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Toffikk wants to merge 2 commits into from
Closed

feat: Add a only javadoc application mode to the parchment plugin #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
287fb8d
feat: Add a only javadoc application mode to the parchment plugin
Toffikk Oct 7, 2025
999b8b1
chore: fixup description
Toffikk Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,8 @@ Usage: jst [-hV] [--debug] [--in-format=<inputFormat>] [--libraries-list=<librar
[--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>]...
[--only-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>]
[--interface-injection-marker=<annotationMarker>]
Expand Down Expand Up @@ -102,6 +102,9 @@ Plugin - parchment
existing variable names
--[no-]parchment-javadoc
Whether Parchment javadocs should be applied
--only-parchment-javadoc
Whether to only apply Parchment javadocs, skipping parameter renaming.
Overrides the --[no-]parchment-javadoc setting
--parchment-mappings=<mappingsPath>
The location of the Parchment mappings file
Plugin - accesstransformers
Expand Down
65 changes: 38 additions & 27 deletions parchment/src/main/java/net/neoforged/jst/parchment/GatherReplacementsVisitor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
class GatherReplacementsVisitor extends PsiRecursiveElementVisitor {
private final NamesAndDocsDatabase namesAndDocs;
private final boolean enableJavadoc;
private final boolean onlyJavadoc;
@Nullable
private final UnaryOperator<String> conflictResolver;
private final Replacements replacements;
Expand All @@ -47,10 +48,12 @@ class GatherReplacementsVisitor extends PsiRecursiveElementVisitor {

public GatherReplacementsVisitor(NamesAndDocsDatabase namesAndDocs,
boolean enableJavadoc,
boolean onlyJavadoc,
@Nullable UnaryOperator<String> conflictResolver,
Replacements replacements) {
this.namesAndDocs = namesAndDocs;
this.enableJavadoc = enableJavadoc;
this.enableJavadoc = enableJavadoc || onlyJavadoc;
this.onlyJavadoc = onlyJavadoc;
this.conflictResolver = conflictResolver;
this.replacements = replacements;
}
Expand Down Expand Up @@ -138,34 +141,40 @@ 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 (!onlyJavadoc) {
// 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 {
// Remap the existing Javadoc @param tags to the param names present in the source
renamedParameters.put(paramName, psiParameter.getName());

parameterOrder.add(psiParameter.getName());
}
} else {
parameterOrder.add(psiParameter.getName());
}
Expand Down Expand Up @@ -208,10 +217,12 @@ else if (PsiHelper.isNonStaticInnerClass(psiMethod.getContainingClass())) {
}
}
} else if (element instanceof PsiReferenceExpression refExpr && refExpr.getReferenceNameElement() != null) {
for (var entry : activeParameters.entrySet()) {
if (refExpr.isReferenceTo(entry.getKey())) {
replacements.replace(refExpr.getReferenceNameElement(), entry.getValue());
break;
if (!onlyJavadoc) {
for (var entry : activeParameters.entrySet()) {
if (refExpr.isReferenceTo(entry.getKey())) {
replacements.replace(refExpr.getReferenceNameElement(), entry.getValue());
break;
}
}
}
}
Expand Down
5 changes: 4 additions & 1 deletion parchment/src/main/java/net/neoforged/jst/parchment/ParchmentTransformer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@ public class ParchmentTransformer implements SourceTransformer {
)
public boolean enableJavadoc = true;

@CommandLine.Option(names = "--only-parchment-javadoc", description = "Whether to only apply Parchment javadocs, skipping parameter renaming. Overrides the --[no-]parchment-javadoc setting")
public boolean onlyJavadoc = false;

@CommandLine.Option(names = "--parchment-conflict-prefix", description = "Apply the prefix specified if a Parchment parameter name conflicts with existing variable names")
public String conflictPrefix;

Expand Down Expand Up @@ -56,7 +59,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, onlyJavadoc, conflictResolver, replacements);
visitor.visitElement(psiFile);
}

Expand Down