Skip to content

Commit

Permalink
Fix and update Javadocs (#98)
Browse files Browse the repository at this point in the history
  • Loading branch information
@NebelNidas
NebelNidas authored Apr 14, 2024
1 parent e92c6f9 commit 3da92ab
Show file tree
Hide file tree
Showing 11 changed files with 45 additions and 123 deletions.
144 changes: 32 additions & 112 deletions src/main/java/net/fabricmc/mappingio/format/MappingFormat.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,122 +21,15 @@
/**
* Represents a supported mapping format. Every format can be assumed to have an associated reader available.
*
* <p>Feature comparison table:
* <table>
* <tr>
* <th>Format</th>
* <th>Namespaces</th>
* <th>Field descriptors</th>
* <th>Comments</th>
* <th>Parameters</th>
* <th>Local variables</th>
* <th>Metadata</th>
* </tr>
* <tr>
* <td>Tiny v1</td>
* <td>✔</td>
* <td>src</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>✔ (Currently limited support)</td>
* </tr>
* <tr>
* <td>Tiny v2</td>
* <td>✔</td>
* <td>src</td>
* <td>✔</td>
* <td>lvIdx & srcName</td>
* <td>lvIdx, lvtIdx, startOpIdx & srcName</td>
* <td>✔</td>
* </tr>
* <tr>
* <td>Enigma</td>
* <td>-</td>
* <td>src</td>
* <td>✔</td>
* <td>lvIdx</td>
* <td>-</td>
* <td>-</td>
* </tr>
* <tr>
* <td>SRG</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* </tr>
* <tr>
* <td>XSRG</td>
* <td>-</td>
* <td>src & dst</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* </tr>
* <tr>
* <td>JAM</td>
* <td>-</td>
* <td>src</td>
* <td>-</td>
* <td>argPos</td>
* <td>-</td>
* <td>-</td>
* </tr>
* <tr>
* <td>CSRG/TSRG</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* </tr>
* <tr>
* <td>TSRG2</td>
* <td>✔</td>
* <td>src</td>
* <td>-</td>
* <td>lvIdx & srcName</td>
* <td>-</td>
* <td>-</td>
* </tr>
* <tr>
* <td>ProGuard</td>
* <td>-</td>
* <td>src</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* </tr>
* <tr>
* <td>Recaf Simple</td>
* <td>-</td>
* <td>src & dst</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* </tr>
* <tr>
* <td>JOBF</td>
* <td>-</td>
* <td>src</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* <td>-</td>
* </tr>
* </table>
* <p>A feature comparison table can be found <a href="https://fabricmc.net/wiki/documentation:mapping_formats">here</a>.
*/
// Format order is determined by importance to Fabric tooling, format family and release order therein.
// Format order is determined by importance to Fabric tooling, format family and release order therein (synced with the table linked above).
public enum MappingFormat {
/**
* The {@code Tiny} mapping format, as specified <a href="https://fabricmc.net/wiki/documentation:tiny">here</a>.
*
* <h2>Implementation notes</h2>
* File metadata only has limited support as of now, and is hardcoded to intermediary counters.
*/
TINY_FILE("Tiny file", "tiny", true, true, false, false, false, true),

Expand All @@ -147,22 +40,34 @@ public enum MappingFormat {

/**
* Enigma's mapping format, as specified <a href="https://fabricmc.net/wiki/documentation:enigma_mappings">here</a>.
*
* <h2>Implementation notes</h2>
* Access modifiers are currently not supported.
*/
ENIGMA_FILE("Enigma file", "mapping", false, true, true, true, false, true),

/**
* Enigma's mapping format (in directory form), as specified <a href="https://fabricmc.net/wiki/documentation:enigma_mappings">here</a>.
*
* <h2>Implementation notes</h2>
* Access modifiers are currently not supported.
*/
ENIGMA_DIR("Enigma directory", null, false, true, true, true, false, true),

/**
* The {@code SRG} ("Searge RetroGuard") mapping format, as specified <a href="https://github.com/MinecraftForge/SrgUtils/blob/67f30647ece29f18256ca89a23cda6216d6bd21e/src/main/java/net/minecraftforge/srgutils/InternalUtils.java#L69-L81">here</a>.
*
* <h2>Implementation notes</h2>
* Package mappings are currently not supported.
*/
SRG_FILE("SRG file", "srg", false, false, false, false, false, true),

/**
* The {@code XSRG} ("Extended SRG") mapping format, as specified <a href="https://github.com/MinecraftForge/SrgUtils/blob/67f30647ece29f18256ca89a23cda6216d6bd21e/src/main/java/net/minecraftforge/srgutils/InternalUtils.java#L69-L84">here</a>.
* Same as SRG, but with field descriptors.
*
* <h2>Implementation notes</h2>
* Package mappings are currently not supported.
*/
XSRG_FILE("XSRG file", "xsrg", false, true, false, false, false, true),

Expand All @@ -173,22 +78,34 @@ public enum MappingFormat {

/**
* The {@code CSRG} ("Compact SRG", since it saves disk space over SRG) mapping format, as specified <a href="https://github.com/MinecraftForge/SrgUtils/blob/67f30647ece29f18256ca89a23cda6216d6bd21e/src/main/java/net/minecraftforge/srgutils/InternalUtils.java#L196-L207">here</a>.
*
* <h2>Implementation notes</h2>
* Package mappings are currently not supported.
*/
CSRG_FILE("CSRG file", "csrg", false, false, false, false, false, true),

/**
* The {@code TSRG} ("Tiny SRG", since it saves disk space over SRG) mapping format, as specified <a href="https://github.com/MinecraftForge/SrgUtils/blob/67f30647ece29f18256ca89a23cda6216d6bd21e/src/main/java/net/minecraftforge/srgutils/InternalUtils.java#L196-L213">here</a>.
* Same as CSRG, but hierarchical instead of flat.
*
* <h2>Implementation notes</h2>
* Package mappings are currently not supported.
*/
TSRG_FILE("TSRG file", "tsrg", false, false, false, false, false, true),

/**
* The {@code TSRG v2} mapping format, as specified <a href="https://github.com/MinecraftForge/SrgUtils/blob/67f30647ece29f18256ca89a23cda6216d6bd21e/src/main/java/net/minecraftforge/srgutils/InternalUtils.java#L262-L285">here</a>.
*
* <h2>Implementation notes</h2>
* Package mappings and static markers for methods are currently not supported.
*/
TSRG_2_FILE("TSRG2 file", "tsrg", true, true, false, true, false, true),

/**
* ProGuard's mapping format, as specified <a href="https://www.guardsquare.com/manual/tools/retrace">here</a>.
*
* <h2>Implementation notes</h2>
* Line numbers are currently not supported.
*/
PROGUARD_FILE("ProGuard file", "txt", false, true, false, false, false, true),

Expand All @@ -199,6 +116,9 @@ public enum MappingFormat {

/**
* The {@code JOBF} mapping format, as specified <a href="https://github.com/skylot/jadx/blob/2d5c0fda4a0c5d16207a5f48edb72e6efa7d5bbd/jadx-core/src/main/java/jadx/core/deobf/DeobfPresets.java">here</a>.
*
* <h2>Implementation notes</h2>
* Package mappings are currently not supported.
*/
JOBF_FILE("JOBF file", "jobf", false, true, false, false, false, true);

Expand Down
2 changes: 1 addition & 1 deletion src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaDirReader.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
import net.fabricmc.mappingio.tree.MemoryMappingTree;

/**
* {@linkplain MappingFormat#ENIGMA_DIRECTORY Enigma directory} reader.
* {@linkplain MappingFormat#ENIGMA_DIR Enigma directory} reader.
*
* <p>Crashes if a second visit pass is requested without
* {@link MappingFlag#NEEDS_MULTIPLE_PASSES} having been passed beforehand.
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaDirWriter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
import net.fabricmc.mappingio.format.MappingFormat;

/**
* {@linkplain MappingFormat#ENIGMA_DIRECTORY Enigma directory} writer.
* {@linkplain MappingFormat#ENIGMA_DIR Enigma directory} writer.
*/
public final class EnigmaDirWriter extends EnigmaWriterBase {
public EnigmaDirWriter(Path dir, boolean deleteExistingFiles) throws IOException {
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/net/fabricmc/mappingio/format/simple/RecafSimpleFileReader.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
import net.fabricmc.mappingio.tree.MemoryMappingTree;

/**
* {@linkplain MappingFormat#RECAF_SIMPLE Recaf Simple file} reader.
* {@linkplain MappingFormat#RECAF_SIMPLE_FILE Recaf Simple file} reader.
*/
public final class RecafSimpleFileReader {
private RecafSimpleFileReader() {
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/net/fabricmc/mappingio/format/simple/RecafSimpleFileWriter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
import net.fabricmc.mappingio.format.MappingFormat;

/**
* {@linkplain MappingFormat#RECAF_SIMPLE Recaf Simple file} writer.
* {@linkplain MappingFormat#RECAF_SIMPLE_FILE Recaf Simple file} writer.
*/
public final class RecafSimpleFileWriter implements MappingWriter {
public RecafSimpleFileWriter(Writer writer) {
Expand Down
3 changes: 2 additions & 1 deletion src/main/java/net/fabricmc/mappingio/format/srg/JamFileWriter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,10 @@
import net.fabricmc.mappingio.MappedElementKind;
import net.fabricmc.mappingio.MappingFlag;
import net.fabricmc.mappingio.MappingWriter;
import net.fabricmc.mappingio.format.MappingFormat;

/**
* {@linkplain net.fabricmc.mappingio.format.MappingFormat#JAM_FILE JAM file} writer.
* {@linkplain MappingFormat#JAM_FILE JAM file} writer.
*/
public final class JamFileWriter implements MappingWriter {
public JamFileWriter(Writer writer) {
Expand Down
5 changes: 3 additions & 2 deletions src/main/java/net/fabricmc/mappingio/format/srg/SrgFileWriter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,11 @@
import net.fabricmc.mappingio.MappedElementKind;
import net.fabricmc.mappingio.MappingFlag;
import net.fabricmc.mappingio.MappingWriter;
import net.fabricmc.mappingio.format.MappingFormat;

/**
* {@linkplain net.fabricmc.mappingio.format.MappingFormat#SRG_FILE SRG file} and
* {@linkplain net.fabricmc.mappingio.format.MappingFormat#XSRG_FILE XSRG file} writer.
* {@linkplain MappingFormat#SRG_FILE SRG file} and
* {@linkplain MappingFormat#XSRG_FILE XSRG file} writer.
*/
public final class SrgFileWriter implements MappingWriter {
public SrgFileWriter(Writer writer, boolean xsrg) {
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/net/fabricmc/mappingio/format/tiny/Tiny1FileReader.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
import net.fabricmc.mappingio.tree.MemoryMappingTree;

/**
* {@linkplain MappingFormat#TINY_1 Tiny v1 file} reader.
* {@linkplain MappingFormat#TINY_FILE Tiny v1 file} reader.
*
* <p>Crashes if a second visit pass is requested without
* {@link MappingFlag#NEEDS_MULTIPLE_PASSES} having been passed beforehand.
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/net/fabricmc/mappingio/format/tiny/Tiny1FileWriter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
import net.fabricmc.mappingio.format.MappingFormat;

/**
* {@linkplain MappingFormat#TINY_1 Tiny v1 file} writer.
* {@linkplain MappingFormat#TINY_FILE Tiny v1 file} writer.
*/
public final class Tiny1FileWriter implements MappingWriter {
public Tiny1FileWriter(Writer writer) {
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/net/fabricmc/mappingio/format/tiny/Tiny2FileReader.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
import net.fabricmc.mappingio.format.MappingFormat;

/**
* {@linkplain MappingFormat#TINY_2 Tiny v2 file} reader.
* {@linkplain MappingFormat#TINY_2_FILE Tiny v2 file} reader.
*
* <p>Crashes if a second visit pass is requested without
* {@link MappingFlag#NEEDS_MULTIPLE_PASSES} having been passed beforehand.
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/net/fabricmc/mappingio/format/tiny/Tiny2FileWriter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
import net.fabricmc.mappingio.format.MappingFormat;

/**
* {@linkplain MappingFormat#TINY_2 Tiny v2 file} writer.
* {@linkplain MappingFormat#TINY_2_FILE Tiny v2 file} writer.
*/
public final class Tiny2FileWriter implements MappingWriter {
public Tiny2FileWriter(Writer writer, boolean escapeNames) {
Expand Down

0 comments on commit 3da92ab

Please sign in to comment.