Skip to content

Add annotater editor - #2658

Merged
Earthcomputer merged 17 commits into
devfrom
annotater
Nov 16, 2026
Merged

Earthcomputer merged 17 commits into
devfrom
annotater

Conversation

@Earthcomputer

Copy link
Copy Markdown
Member

Adds an editor for annotater, Fabric's new Javadocs thing, allowing users to edit them and contribute from within the IDE.

Javadocs from the annotater appear as inlay hints in the Minecraft code, allowing the Javadoc to be changed while editing, while not physically changing the source code (which would break a lot of things). They appear as code with basic highlighting (not full highlighting) due to the complexity of running full highlighting. They are also not rendered like docs normally are in reader view, as that would require either some very hacky code or lots of code duplication.

When editing a Javadoc, the corresponding inlay hint is replaced with a mini editor. The text in this editor is a copy of the main Java file with Javadocs added, with all the code before and after the doc comment that is being edited folded out, so it appears that the editor only contains the doc comment. This enables the full Javadoc editing features of the IDE within this mini editor.

This feature has two modes: managed mode and custom mode. In custom mode, you point the mcdev to your own annotater clone, mcdev makes the edits but you handle the git operations required to contribute yourself. In managed mode, mcdev handles all the git stuff for you, including the clone and pull requests, packaging changelists into "contributions" (branches). This is to lower the barrier to contribution, increasing the likelihood that someone will fix an issue or document something on the fly as they are working on their own mod, without getting too sidetracked making an annotater clone.

I'll make a video demo shortly.

AI disclosure: this code was written using an AI agent, with multiple rounds of review and some manual edits.

@Earthcomputer

Copy link
Copy Markdown
Member Author

Video showcase: https://youtu.be/V_Vlk1lwMHU

@DenWav DenWav left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some questions & comments

tasks.runIde {
maxHeapSize = "2G"
jvmArgs("--add-exports=java.base/jdk.internal.vm=ALL-UNNAMED")
systemProperty("mcdev.annotater.upstream", "Earthcomputer/annotater")

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this intentional?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I was going to remove it then I decided not to, as I don't want us to accidentally PR to upstream while testing in the future. I can remove it if you want though

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No that makes sense, though that means everyone that uses that task to test a change will target your repo. Maybe the default value could be some "you need to set this" string to force anyone who tests it to set that value in their gradle.properties?

waitForFork(api, forkName, indicator)

indicator.text = MCDevBundle("fabric.annotater.pr.pushing")
git.push(project, checkout, cloneUrl, request.branch)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might want something like

val pushUrl = URI(cloneUrl).let { uri ->
    URI(uri.scheme, forkOwner, uri.host, uri.port, uri.path, uri.query, uri.fragment).toString()
}
git.push(project, checkout, pushUrl, request.branch)

here to prevent trying to push with the wrong auth (e.g. if the user is logged in or has multiple git profiles in their environment).

That would create a uri like https://DenWav@github.com/DenWav/annotator.git.

forkOwner@ ties the push to the auth provider of the identity the user selected when they created the fork.

But the git.push code goes through git4idea which theoretically could be set up with a different account.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I presumed that git4idea would handle all of this. Does it not?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe it does, I just don't know how it handles if you have multiple identities configured. But I'm not that worried about it, you can ignore this.

waitForFork(api, forkName, indicator)

indicator.text = MCDevBundle("fabric.annotater.pr.pushing")
git.push(project, checkout, cloneUrl, request.branch)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if a user tries to do this on a PR that is closed? And a closed PR's branch may be deleted too.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It pushes to a branch, recreating it if it doesn't exist. It doesn't recreate the pull request due to the check below. We might want a warning to the user that they are adding to an open (or closed) pull request, that's easy to do by accident.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense, and yeah a warning is a good idea. It would probably happen all the time, since I assume that would happen if someone just forget to change it after a PR is merged.

if (existing != null && showJavadocs) {
newFolds += existing.textRange
}
val javadoc = checkout.javadocStore.getOrNull(target) ?: continue

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This block of code will remove all javadoc in the file, even if annotator doesn't have javadoc to replace it with.

AnnotaterCheckoutService.checkoutFor checks that the annotator feature is enabled, but that setting is persistent across the whole IDE. If a user enables it for a Fabric project and then opens a NeoForged project, annotator will still run. That's fine and probably intended, but in that case any Parchment javadoc will disappear from the editor even if there isn't an annotator javadoc to replace it.

Just move this line up to above to right below val target = AnnotaterJavadocTarget.fromPsi(member) ?: continue so the continue will hit if there's no javadoc before the fold gets added.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is actually what I intended. For example if you want to remove a doc comment to be deleted from annotater, but you have annotater also applied via loom, you want to be able to see the deletion easily. Annotater is like a distinct mode in which you can view (and edit) Minecraft code, and there's a banner at the top constantly reminding you that you're in this mode

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gotcha, thanks for the explanation.

val member = AnnotaterJavadocEditing.normalize(element) ?: return null
val checkout = AnnotaterJavadocRendering.checkoutForDisplay(member) ?: return null
val target = AnnotaterJavadocTarget.fromPsi(member) ?: return null
return AnnotaterJavadocRendering.generateDoc(member, checkout.javadocStore.getOrNull(target))

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same issue as the other comment, don't do this if there isn't any javadoc to provide. So do:

val javadoc = checkout.javadocStore.getOrNull(target) ?: return null
return AnnotaterJavadocRendering.generateDoc(member, javadoc)

instead.

@Earthcomputer

Copy link
Copy Markdown
Member Author

Added the warning
image

@Earthcomputer
Earthcomputer merged commit 19b7b6f into dev Nov 16, 2026
4 of 6 checks passed
@Earthcomputer
Earthcomputer deleted the annotater branch November 16, 2026 02:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants