feat: re-add Javadoc support via source post-processing#240
Open
bouclem wants to merge 1 commit into
Open
Conversation
Reads class and field comments from the Tiny mapping file and injects them as Javadoc blocks above the matching declarations after Fernflower decompiles. Implemented as a new Source modification step in TaskDecompile, runs after patches and existing source adapters. Method comments are intentionally skipped: matching overloads from rewritten source without a real Java parser is not reliable enough. Brace-depth tracking with quote/comment skipping limits insertions to top-level type members so locals and inner-class members are never touched. Refs MCPHackers#220
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #220
Background
TinyJavadocProviderandSimpleJavadocProviderexist in the tree but are entirely commented out, including theirpackagelines. They referencede.fernflower.main.providers.IJavadocProvider. Checking the publishedio.github.lassebq:fernflower:1.0.0artifact confirms that interface does not exist in the jar, andBaseDecompileronly has the 4-arg constructor(IBytecodeProvider, IResultSaver, Map, IFernflowerLogger). TheLassebq/Fernflowersource likewise has noproviderspackage and no tags or releases beyondmaster.So uncommenting was not an option, and bumping the dependency wasn't either.
What this does
Adds Javadoc comments to the decompiled output by post-processing the generated
.javafiles instead of going through Fernflower's provider hook. Two new files in their owntools/javadocpackage, plus one wiring line inTaskDecompile.JavadocMappingsreads the existing Tiny mapping file (conf/mappings.tiny) using the project's existingmapping-iodependency and collects class and field comments keyed by thenamednamespace. No new dependencies.JavadocSourceextends the existingSourcebase class. It tracks brace depth with quote and comment skipping so it only documents the top-level type and its direct field members. Locals, inner-class members, anonymous bodies, and anything that looks ambiguous are left alone. Skips re-documenting anything that already has a*/block above it, so re-runs are idempotent.TaskDecompilecalls the newSource.modifystep in the existing patch stage, after patches and afterMCP.SOURCE_ADAPTERS. If the mapping file has no comments the step is a no-op.Method comments are intentionally not handled. Without a real Java parser, matching overloads from regenerated source is not reliable enough and silent wrong-doc bugs are worse than no doc.
Files
src/main/java/org/mcphackers/mcp/tools/javadoc/JavadocMappings.javasrc/main/java/org/mcphackers/mcp/tools/javadoc/JavadocSource.javasrc/main/java/org/mcphackers/mcp/tasks/TaskDecompile.java(3 import lines, 1 call)The two existing commented-out provider files (
SimpleJavadocProvider,TinyJavadocProvider) were left untouched on purpose — they target a Fernflower API that does not currently exist on the classpath, so removing them is a separate decision for the project.Testing
gradlew compileJava- clean.Source.modifypipeline and the path layout produced bySource.modifycallers.