Java documentation incompatible with standard NeoForge gradle

[no-name-provided]

Describe the bug
The "val" keyword isn't available in Java projects. Similarly, String::class needs to be replaced by String.class. Are you implicitly assuming a Kotlin environment?

I'd also recommend replacing your placeholder with a valid version specification and commenting about changing it to the desired version.

To Reproduce
n/a

Expected behavior
The setup snippets to work out-of-the-box, or contain comments describing how they can be modified. As-is, it causes unnecessary headaches.

Screenshots
n/a

Desktop (please complete the following information):
n/a

Additional context
Add any other context about the problem here.
Page with suboptimal code: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/

[no-name-provided]

Additionally, your suggested neoforge.mods.toml entry appears incorrectly formatted. I believe it should be [modproperties."${mod_id}"."yumi:entrypoints"].

Did anyone actually try running the documentation in a Neo context?

[ENDERZOMBI102]

You realized those snippets are for the buildscript (build.gradle.kts) right?

[LambdAurora]

Hello.

The "val" keyword isn't available in Java projects. Similarly, String::class needs to be replaced by String.class. Are you implicitly assuming a Kotlin environment?

This part of the documentation is for Gradle buildscripts (build.gradle.kts), the given example is designed for the Kotlin DSL.
It is possible to adapt said code to the Groovy DSL rather easily, our documentation considers that the user is well-acquainted with Gradle and knows how the differences between the Kotlin and the Groovy DSLs.
Here's a known reference to how to do it with the Groovy DSL.

Additionally, your suggested neoforge.mods.toml entry appears incorrectly formatted. I believe it should be [modproperties."${mod_id}"."yumi:entrypoints"].

Is it? The characters allowed for a mod ID/namespace is very restricted, as such it should not cause TOML formatting issues.
This is a snippet that has been tested in multiple mods so far and has worked fine.
I'll add the quotes just in case though, better be safe than sorry.

I'd also recommend replacing your placeholder with a valid version specification and commenting about changing it to the desired version.

Honestly I'd like to have a drop-down to select the version directly and have it auto-filled, but that's a bit more work and we do not currently can afford time in such development.

---

As an aside, while I can understand your frustration, I'd appreciate if we could avoid some of the passive-aggressive remarks.
We're more than happy to assist, and try to lower friction.

[no-name-provided]

I wasn't being passive aggressive. Why did you think I was? Please be specific.

As I've already solved these problems, they are unlikely to affect me going forward. However, they may affect others and (I assume) they weren't intentional. This is a constructive notification that your documentation has problems. I hope you don't interpret any issue report as "aggression", passive or otherwise.

To address your concerns:

1. Each issue I mentioned was reported by IntelliJ as an error, including the lack of quotes in the toml.
2. It's unrealistic to assume Java devs are familiar with Kotlin. If you do, this should be explicitly specified.
   • As far as I'm aware, there's no particular reason not to use Java syntax, explicitly specify the type of that variable, or inline its definition. "Getting started" documentation should generally be written for the lowest denominator, and the most limited dev environment.
   • If you're choosing not to support the majority of NeoForge mods, you should probably change your advertising. Otherwise, you should update your documentation.
3. I mentioned the version number spec because you don't provide your standard for version numbers, or an example, so your documentation is incomplete. I'm personally familiar with common modded versioning practices, and where to find version numbers, so I guessed the string easily, but others might need a few attempts.

[LambdAurora]

Each issue I mentioned was reported by IntelliJ as an error, including the lack of quotes in the toml.

The lack of quotes should not be an issue once the mod is compiled as Gradle would have done string substitution, making the identifier valid. But I probably should've thought of Intellij not recognizing a template. As said, this has been fixed in the documentation now.

It's unrealistic to assume Java devs are familiar with Kotlin. If you do, this should be explicitly specified.

• As far as I'm aware, there's no particular reason not to use Java syntax, explicitly specify the type of that variable, or inline its definition. "Getting started" documentation should generally be written for the lowest denominator, and the most limited dev environment.
• If you're choosing not to support the majority of NeoForge mods, you should probably change your advertising. Otherwise, you should update your documentation.

This snippet of code is specifically for the Gradle buildscripts, for which there is no Java syntax, there's only the Kotin and Groovy DSLs. And the current standard that is pushed by Gradle is the Kotlin DSL.
I'm not sure where this confusion comes from?
Especially since all the other code snippets of actual mod code is in Java.

I mentioned the version number spec because you don't provide your standard for version numbers, or an example, so your documentation is incomplete. I'm personally familiar with common modded versioning practices, and where to find version numbers, so I guessed the string easily, but others might need a few attempts.

Understood, and makes sense.
I could add a note about looking at the Git tags on this repository or a link to the Maven repository as a stopgap measure then?

---

I wasn't being passive aggressive. Why did you think I was? Please be specific.

We've interpreted "Did anyone actually try running the documentation in a Neo context?" and "Page with suboptimal code" as passive-aggressive. If this wasn't your intention, then I'm sorry, all is good.

I hope you don't interpret any issue report as "aggression", passive or otherwise.

We usually do not. We try to take care of each issue to the best of our abilities.
As such, we thank you for notifying us of said issues and giving us food for thought.

[no-name-provided]

The lack of quotes should not be an issue once the mod is compiled as Gradle would have done string substitution, making the identifier valid.

Interesting. You appear to be correct. I agree that it's generally best to suppress warnings/errors anyway, but it seems I overestimated the severity of the problem.

This snippet of code is specifically for the Gradle buildscripts, for which there is no Java syntax, there's only the Kotin and Groovy DSLs. And the current standard that is pushed by Gradle is the Kotlin DSL.
I'm not sure where this confusion comes from?
Especially since all the other code snippets of actual mod code is in Java.

My impression is that Kotlin isn't widely used in the NeoForge community. The default NeoForge build scripts, provided by either their official mod generator* or the Minecraft Development Plugin, don't support val. As far as I can tell, "val" is a keyword exclusive to Kotlin. I have moderate experience with Python, JavaScript (dated), C#, etc. I did not recognize it, and the error message was unhelpful. (Fortunately, StackOverflow was helpful.) I think a NeoForge tutorial should include code that works with the default buildscripts, even if they use a standard that is now considered dated.

I recommend making sure your startup code is copy-paste compatible with the official templates. At the very least, you should provide instructions for converting your examples. I suspect those of us who aren't professional devs usually don't spend much time fiddling with buildscripts, and aren't likely to be familiar with the latest trends. And, as I said, familiarity with Kotlin isn't generally necessary for Minecraft modding.

We've interpreted "Did anyone actually try running the documentation in a Neo context?" and "Page with suboptimal code" as passive-aggressive. If this wasn't your intention, then I'm sorry, all is good.

All good, then. It was a genuine question, based on the recency of your NeoForge support, the general impression I had of your docs being a recent generalization of Fabric documentation, how easily the compiler flagged these issues, and not knowing if the documentation was crowdsourced. If you had said no, I would have stopped nitpicking and simply recommended you make a stock NeoForge mod generator mod and give your docs a proper test. I still suspect that would be a good idea, as this simulates the experience most NeoForge modders will have, but it sounds like you have tested your doc's code examples & instructions in a NeoForge environment and are generally happy with the results.

Still not sure what's aggressive about suboptimal. Would it have been less offensive if I said "bad", "buggy", or "in need of some love"? I wouldn't be opening a bug report if it were perfect.

---

To summarize the answers to my questions/suggestions, and my reactions:
Q: Are you implicitly assuming a Kotlin environment?
A: Yes. That is the modern standard.
R. Default Neo buildscripts aren't on that standard. You should make your wiki backwards compatible.

S: You should document your version numbering scheme. The docs are a bit ambiguous here.
A: I should, but the way I want to do it is kind of hard. Might add a stopgap comment.
R: Sounds like a plan.

Q: Are you missing a pair of quotes?
A: Yes, but it's not important. Will fix anyway.
R: Cool.

Q: Has anyone tested this?
A: Yes.
R: Hmm... well, then there's no point stopping this discussion while you do that. You might want to give it another run through with the default Neo mod template, if you haven't already, and make sure your docs have enough info for newbs.

---

*There are actually two default buildscripts provided by this generator. I haven't familiarized myself with the second.