search

MinecraftForge / MinecraftForge

Modifications to the Minecraft base files to assist in compatibility between mods. New Discord: https://discord.minecraftforge.net/
https://files.minecraftforge.net/
Other
6.78k stars 2.65k forks source link

Javadoc doesn't build. #9832

Open JontomXire opened 6 months ago

JontomXire commented 6 months ago

Minecraft Version: 1.20.x

Forge Version: Branch 1.20.x, commit ed2ba0f

Logs:

Task :fmlloader:compileJava /home/jx/Development/MinecraftForge/fmlloader/src/main/java/net/minecraftforge/fml/loading/RuntimeDistCleaner.java:160: warning: [unchecked] getExtension() in RuntimeDistCleaner implements getExtension() in ILaunchPluginService public Consumer getExtension() ^ return type requires unchecked conversion from Consumer to T where T is a type-variable: T extends Object declared in method getExtension() Note: /home/jx/Development/MinecraftForge/fmlloader/src/main/java/net/minecraftforge/fml/loading/StringUtils.java uses or overrides a deprecated API. Note: Recompile with -Xlint:deprecation for details. Note: Some input files use or override a deprecated API that is marked for removal. Note: Recompile with -Xlint:removal for details. 1 warning

Task :fmlcore:compileJava Note: /home/jx/Development/MinecraftForge/fmlcore/src/main/java/net/minecraftforge/fml/ModStateManager.java uses or overrides a deprecated API that is marked for removal. Note: Recompile with -Xlint:removal for details.

Task :fmlcore:javadoc /home/jx/Development/MinecraftForge/fmlcore/src/main/java/net/minecraftforge/fml/IExtensionPoint.java:93: error: reference not found

  • @see net.minecraftforge.network.ServerStatusPing ^ /home/jx/Development/MinecraftForge/fmlcore/src/main/java/net/minecraftforge/fml/IExtensionPoint.java:94: error: reference not found
  • @see net.minecraftforge.client.ForgeHooksClient#processForgeListPingData(net.minecraft.network.protocol.status.ServerStatus, net.minecraft.client.multiplayer.ServerData) ^

Steps to Reproduce:

  1. ./gradlew setup
  2. ./gradlew javadoc

If these are not the correct steps to generate the javadocs, then what are? I cannot find any up to date information on generating javadocs on the command line (Linux).

Description of issue:

Javadocs are not generated.

This was also reported in December 2022 on the forums at https://forums.minecraftforge.net/topic/118731-is-there-a-forge-api-or-javadoc/ where the OP states "I have unsuccessfully tried to create the Javadoc from the MinecraftForge Github repository.".

This issue may be resolved by adding documentation on the steps required to generate the JavaDocs, of which there currently appears to be none.

JontomXire commented 6 months ago

Also, at the start of the build I get:

> Configure project :
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
JontomXire commented 6 months ago

After removing the two lines that caused errors, I get:

`> Task :fmlearlydisplay:javadoc FAILED /home/alastair/Development/MinecraftForge/fmlearlydisplay/src/main/java/net/minecraftforge/fml/earlydisplay/DisplayWindow.java:343: error: invalid use of @return

FAILURE: Build failed with an exception.

I assume that people do actually use JavaDoc when creating mods, rather than some sort of psychic power that I lack, and as such that they manage to actually generate the javadocs? But this is getting silly!

LexManos commented 6 months ago

Most people do not use stand alone javadoc, they use their IDE to navigate around the source and read the docs it displays. So ya, some of the javadocs in the project may not pass the javadoc parser's strict requirements. You could try adding the -Xdoclint:none argument to lessen the strictness. If you wanna do a PR that fixes the javadoc issues, feel free. But as I said, most people don't care these days.

JontomXire commented 6 months ago

What is the syntax to specify "-Xdoclint:non"? Where do I add this?

I tried:

$ ./gradlew -Xdoclint:none javadoc

Unknown command-line option '-X'.
JontomXire commented 6 months ago

Many of the bugs are documentation errors. Whether the documentation refers to a parameter that does not exist or has had a name change, or the documentation refers to a class or somesuch that no longer exists.

I am fixing things as best as I can, but in the case of some "reference not found" errors I am simply deleting the relevant sentence.

JontomXire commented 6 months ago

Do I have to clone to do a push request? I created a branch from 1.20.x but cannot push it or the changes on it.

I would prefer not to clone just to create a merge request so I am attaching the diffs here. MinecraftForge_diffs.txt

JontomXire commented 6 months ago

Also, the generated javadoc does not include any of the underlying Minecraft stuff, which is the stuff I am really after! How do I generate javadocs like these: https://nekoyue.github.io/ForgeJavaDocs-NG/javadoc/1.19.3/