diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c18ffd8..4c0a2b00 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +- Improved documentation - Fixed NPE in `MemoryMappingTree` - Fixed TSRG2 reader not handling multiple passes correctly diff --git a/README.md b/README.md index a0ef3337..56633184 100644 --- a/README.md +++ b/README.md @@ -3,18 +3,18 @@ Mapping-IO is a small and efficient library for working with deobfuscation mappi The API is inspired by ObjectWeb's [ASM](https://asm.ow2.io/): At its core, Mapping-IO is [visitor-based](./src/main/java/net/fabricmc/mappingio/MappingVisitor.java), but it also provides a [tree API](./src/main/java/net/fabricmc/mappingio/tree/) for in-memory storage and easier data manipulation. -Utilities for more sophisticated use cases can be found in the [mapping-io-extras](./mapping-io-extras/) module; they've been moved out from the core publication due to their additional dependency requirements. +Utilities for more sophisticated use cases can be found in the [mapping-io-extras](./mapping-io-extras/) module; they've been moved out from the core publication due to their additional dependencies. ## Usage -Reading and writing can be easily be achieved via the [`MappingReader`](./src/main/java/net/fabricmc/mappingio/MappingReader.java) and [`MappingWriter`](./src/main/java/net/fabricmc/mappingio/MappingWriter.java) interfaces: +Reading and writing can be easily achieved via the [`MappingReader`](./src/main/java/net/fabricmc/mappingio/MappingReader.java) and [`MappingWriter`](./src/main/java/net/fabricmc/mappingio/MappingWriter.java) interfaces: ```java MappingReader.read(inputPath, /* optional */ inputFormat, MappingWriter.create(outputPath, outputFormat)); ``` -The above example reads mappings from the input path directly into a mapping writer, writing all contents to disk in the specified mapping format. -Keep in mind that the conversion process might be lossy if the two formats' feature sets differ; see the comparison table [here](./src/main/java/net/fabricmc/mappingio/format/MappingFormat.java) for more information. +The above example reads mappings from the input path directly into a `MappingWriter`, writing all contents to disk in the specified format. +Keep in mind that the conversion process might be lossy if the two formats' feature sets differ; see the comparison table [here](./src/main/java/net/fabricmc/mappingio/format/MappingFormat.java) for more details. You can also read into a tree first: ```java @@ -25,8 +25,23 @@ MappingReader.read(inputPath, inputFormat, tree); tree.accept(MappingWriter.create(outputPath, outputFormat)); ``` -If the input format is known and more direct control over specific reading parameters is desired, the formats' readers (or writers) may also be invoked directly. +If the input format is known beforehand and more direct control over specific reading parameters is desired, the formats' readers (or writers) may also be invoked directly. -Mapping manipulation is achieved either via the tree API and/or specialized `MappingVisitor`s, hand-crafted or using pre-made ones found in the [adapter](./src/main/java/net/fabricmc/mappingio/adapter/) package. +Mapping manipulation is achieved either via the tree API or specialized `MappingVisitor`s, hand-crafted or utilizing first-party ones found in the [adapter](./src/main/java/net/fabricmc/mappingio/adapter/) package. -For more information, please consult the project's Javadoc comments. +For further information, please consult the project's Javadocs. + + +### Maven +Mapping-IO is available from the [FabricMC Maven](https://maven.fabricmc.net/net/fabricmc/mapping-io), version 0.4.2 and onwards can also be found on Maven Central. + +Gradle snippet: +```gradle +repositories { + mavenCentral() +} + +dependencies { + api 'net.fabricmc:mapping-io:${mappingio_version}' +} +``` diff --git a/mapping-io-extras/src/main/java/net/fabricmc/mappingio/extras/MappingTreeRemapper.java b/mapping-io-extras/src/main/java/net/fabricmc/mappingio/extras/MappingTreeRemapper.java index fd19ca35..b6701c43 100644 --- a/mapping-io-extras/src/main/java/net/fabricmc/mappingio/extras/MappingTreeRemapper.java +++ b/mapping-io-extras/src/main/java/net/fabricmc/mappingio/extras/MappingTreeRemapper.java @@ -23,7 +23,7 @@ import net.fabricmc.mappingio.tree.MappingTreeView; /** - * An ASM remapper that remaps between two namespaces in a {@link MappingTreeView}. + * An ASM {@link Remapper} that remaps between two namespaces in a {@link MappingTreeView}. */ public final class MappingTreeRemapper extends Remapper { private final MappingTreeView tree; @@ -33,9 +33,9 @@ public final class MappingTreeRemapper extends Remapper { /** * Constructs a {@code MappingTreeRemapper}. * - * @param tree the mapping tree view - * @param from the input namespace, must be in the tree - * @param to the output namespace, must be in the tree + * @param tree The mapping tree view. + * @param from The input namespace, must be in the tree. + * @param to The output namespace, must be in the tree. */ public MappingTreeRemapper(MappingTreeView tree, String from, String to) { Objects.requireNonNull(tree, "Mapping tree cannot be null"); diff --git a/src/main/java/net/fabricmc/mappingio/FlatMappingVisitor.java b/src/main/java/net/fabricmc/mappingio/FlatMappingVisitor.java index e8e3ae5f..a495f8a0 100644 --- a/src/main/java/net/fabricmc/mappingio/FlatMappingVisitor.java +++ b/src/main/java/net/fabricmc/mappingio/FlatMappingVisitor.java @@ -28,6 +28,9 @@ import net.fabricmc.mappingio.adapter.FlatAsRegularMappingVisitor; import net.fabricmc.mappingio.adapter.RegularAsFlatMappingVisitor; +/** + * A mapping visitor that provides the entire data for a given element within a single visit call. + */ public interface FlatMappingVisitor { default Set getFlags() { return MappingFlag.NONE; @@ -40,7 +43,7 @@ default void reset() { /** * Determine whether the header (namespaces, metadata if part of the header) should be visited. * - * @return true if the header is to be visited, false otherwise + * @return {@code true} if the header is to be visited, {@code false} otherwise. */ default boolean visitHeader() throws IOException { return true; @@ -53,7 +56,7 @@ default void visitMetadata(String key, @Nullable String value) throws IOExceptio /** * Determine whether the mapping content (classes and anything below, metadata if not part of the header) should be visited. * - * @return true if content is to be visited, false otherwise + * @return {@code true} if content is to be visited, {@code false} otherwise. */ default boolean visitContent() throws IOException { return true; @@ -96,7 +99,8 @@ void visitMethodVarComment(String srcClsName, String srcMethodName, @Nullable St /** * Finish the visitation pass. - * @return true if the visitation pass is final, false if it should be started over + * + * @return {@code true} if the visitation pass is final, {@code false} if it should be started over. */ default boolean visitEnd() throws IOException { return true; diff --git a/src/main/java/net/fabricmc/mappingio/MappedElementKind.java b/src/main/java/net/fabricmc/mappingio/MappedElementKind.java index 87c20e35..a046c5f1 100644 --- a/src/main/java/net/fabricmc/mappingio/MappedElementKind.java +++ b/src/main/java/net/fabricmc/mappingio/MappedElementKind.java @@ -16,6 +16,9 @@ package net.fabricmc.mappingio; +/** + * A kind of element that can be mapped. + */ public enum MappedElementKind { CLASS(0), FIELD(1), diff --git a/src/main/java/net/fabricmc/mappingio/MappingFlag.java b/src/main/java/net/fabricmc/mappingio/MappingFlag.java index 0285d41f..2271b9f0 100644 --- a/src/main/java/net/fabricmc/mappingio/MappingFlag.java +++ b/src/main/java/net/fabricmc/mappingio/MappingFlag.java @@ -20,6 +20,9 @@ import java.util.EnumSet; import java.util.Set; +/** + * Flags a {@link MappingVisitor} may provide to inform the caller about certain requirements. + */ public enum MappingFlag { /** * Indication that the visitor may require multiple passes. diff --git a/src/main/java/net/fabricmc/mappingio/MappingReader.java b/src/main/java/net/fabricmc/mappingio/MappingReader.java index 854f7c1e..0deae9bf 100644 --- a/src/main/java/net/fabricmc/mappingio/MappingReader.java +++ b/src/main/java/net/fabricmc/mappingio/MappingReader.java @@ -58,7 +58,7 @@ public static MappingFormat detectFormat(Reader reader) throws IOException { int pos = 0; int len; - // Be careful not to close the reader, thats upto the caller. + // Be careful not to close the reader, that's up to the caller. BufferedReader br = reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader); br.mark(DETECT_HEADER_LEN); @@ -177,24 +177,39 @@ public static List getNamespaces(Reader reader, MappingFormat format) th } } - public static void read(Path file, MappingVisitor visitor) throws IOException { - read(file, null, visitor); + /** + * Tries to detect the format of the given path and read it. + * + * @param path The path to read from. Can be a file or a directory. + * @param visitor The receiving visitor. + * @throws IOException If the format can't be detected or reading fails. + */ + public static void read(Path path, MappingVisitor visitor) throws IOException { + read(path, null, visitor); } - public static void read(Path file, MappingFormat format, MappingVisitor visitor) throws IOException { + /** + * Tries to read the given path using the passed format's reader. + * + * @param path The path to read from. Can be a file or a directory. + * @param format The format to use. Has to match the path's format. + * @param visitor The receiving visitor. + * @throws IOException If reading fails. + */ + public static void read(Path path, MappingFormat format, MappingVisitor visitor) throws IOException { if (format == null) { - format = detectFormat(file); + format = detectFormat(path); if (format == null) throw new IOException("invalid/unsupported mapping format"); } if (format.hasSingleFile()) { - try (Reader reader = Files.newBufferedReader(file)) { + try (Reader reader = Files.newBufferedReader(path)) { read(reader, format, visitor); } } else { switch (format) { case ENIGMA_DIR: - EnigmaDirReader.read(file, visitor); + EnigmaDirReader.read(path, visitor); break; default: throw new IllegalStateException(); @@ -202,10 +217,25 @@ public static void read(Path file, MappingFormat format, MappingVisitor visitor) } } + /** + * Tries to detect the reader's content's format and read it. + * + * @param reader The reader to read from. + * @param visitor The receiving visitor. + * @throws IOException If the format can't be detected or reading fails. + */ public static void read(Reader reader, MappingVisitor visitor) throws IOException { read(reader, null, visitor); } + /** + * Tries to read the reader's content using the passed format's mapping reader. + * + * @param reader The reader to read from. + * @param format The format to use. Has to match the reader's content's format. + * @param visitor The receiving visitor. + * @throws IOException If reading fails. + */ public static void read(Reader reader, MappingFormat format, MappingVisitor visitor) throws IOException { if (format == null) { if (!reader.markSupported()) reader = new BufferedReader(reader); diff --git a/src/main/java/net/fabricmc/mappingio/MappingVisitor.java b/src/main/java/net/fabricmc/mappingio/MappingVisitor.java index c4931584..24f78dec 100644 --- a/src/main/java/net/fabricmc/mappingio/MappingVisitor.java +++ b/src/main/java/net/fabricmc/mappingio/MappingVisitor.java @@ -54,7 +54,7 @@ default Set getFlags() { } /** - * Reset the visitor including any chained visitors to allow for another independent visit (excluding visitEnd=false). + * Reset the visitor, including any chained visitors, to allow for another independent visit (excluding visitEnd=false). */ default void reset() { throw new UnsupportedOperationException(); @@ -63,7 +63,7 @@ default void reset() { /** * Determine whether the header (namespaces, metadata if part of the header) should be visited. * - * @return true if the header is to be visited, false otherwise + * @return {@code true} if the header is to be visited, {@code false} otherwise. */ default boolean visitHeader() throws IOException { return true; @@ -76,21 +76,61 @@ default void visitMetadata(String key, @Nullable String value) throws IOExceptio /** * Determine whether the mapping content (classes and anything below, metadata if not part of the header) should be visited. * - * @return true if content is to be visited, false otherwise + * @return {@code true} if content is to be visited, {@code false} otherwise. */ default boolean visitContent() throws IOException { return true; } + /** + * Visit a class. + * + * @param srcName The fully qualified source name of the class, in internal form + * (slashes instead of dots, dollar signs for delimiting inner classes). + * @return Whether or not the class's content should be visited too. + */ boolean visitClass(String srcName) throws IOException; boolean visitField(String srcName, @Nullable String srcDesc) throws IOException; boolean visitMethod(String srcName, @Nullable String srcDesc) throws IOException; + + /** + * Visit a parameter. + * + * @param argPosition Always starts at 0 and gets incremented by 1 for each additional parameter. + * @param lvIndex The parameter's local variable index in the current method. + * Starts at 0 for static methods, 1 otherwise. For each additional parameter, + * it gets incremented by 1, or by 2 if it's a primitive {@code long} or {@code double}. + * @param srcName The optional source name of the parameter. + * @return Whether or not the arg's content should be visited too. + */ boolean visitMethodArg(int argPosition, int lvIndex, @Nullable String srcName) throws IOException; + + /** + * Visit a variable. + * + * @param lvtRowIndex The variable's index in the method's LVT + * (local variable table). It is optional, so -1 can be passed instead. + * This is the case since LVTs themselves are optional debug information, see + * JVMS 4.7.13. + * @param lvIndex The var's local variable index in the current method. For each additional variable, + * it gets incremented by 1, or by 2 if it's a primitive {@code long} or {@code double}. + * The first variable starts where the last parameter left off (plus the offset). + * @param startOpIdx Required for cases when the lvIndex alone doesn't uniquely identify a local variable. + * This is the case when variables get re-defined later on, in which case most decompilers opt to + * not re-define the existing var, but instead generate a new one (with both sharing the same lvIndex). + * @param endOpIdx Counterpart to startOpIdx. Exclusive. + * @param srcName The optional source name of the variable. + * @return Whether or not the var's content should be visited too. + */ boolean visitMethodVar(int lvtRowIndex, int lvIndex, int startOpIdx, int endOpIdx, @Nullable String srcName) throws IOException; /** * Finish the visitation pass. - * @return true if the visitation pass is final, false if it should be started over + * + *

Implementors may throw an exception if a second pass is requested without the {@code NEEDS_MULTIPLE_PASSES} + * flag having been passed beforehand, but only if that behavior is documented. + * + * @return {@code true} if the visitation pass is final, {@code false} if it should be started over. */ default boolean visitEnd() throws IOException { return true; @@ -99,8 +139,8 @@ default boolean visitEnd() throws IOException { /** * Destination name for the current element. * - * @param namespace namespace index, index into the dstNamespaces List in {@link #visitNamespaces} - * @param name destination name + * @param namespace Namespace index (index into the dstNamespaces list in {@link #visitNamespaces}). + * @param name Destination name. */ void visitDstName(MappedElementKind targetKind, int namespace, String name) throws IOException; @@ -114,7 +154,7 @@ default void visitDstDesc(MappedElementKind targetKind, int namespace, String de * *

This is also a notification about all available dst names having been passed on. * - * @return true if the contents are to be visited, false otherwise + * @return {@code true} if the contents are to be visited, {@code false} otherwise */ default boolean visitElementContent(MappedElementKind targetKind) throws IOException { return true; @@ -123,7 +163,7 @@ default boolean visitElementContent(MappedElementKind targetKind) throws IOExcep /** * Comment for the specified element (last content-visited or any parent). * - * @param comment comment as a potentially multi-line string + * @param comment Comment as a potentially multi-line string. */ void visitComment(MappedElementKind targetKind, String comment) throws IOException; } diff --git a/src/main/java/net/fabricmc/mappingio/adapter/FlatAsRegularMappingVisitor.java b/src/main/java/net/fabricmc/mappingio/adapter/FlatAsRegularMappingVisitor.java index f5cbf412..0ce63765 100644 --- a/src/main/java/net/fabricmc/mappingio/adapter/FlatAsRegularMappingVisitor.java +++ b/src/main/java/net/fabricmc/mappingio/adapter/FlatAsRegularMappingVisitor.java @@ -28,6 +28,13 @@ import net.fabricmc.mappingio.MappingFlag; import net.fabricmc.mappingio.MappingVisitor; +/** + * A mapping visitor that forwards all relevant data to a {@link FlatMappingVisitor}. + * + *

Element data is relayed upon {@link #visitElementContent(MappedElementKind)} + * or {@link #visitComment(MappedElementKind, String)} invocation. + * If no data was collected for the current element, the corresponding {@link FlatMappingVisitor}'s visit method is not called. + */ public final class FlatAsRegularMappingVisitor implements MappingVisitor { public FlatAsRegularMappingVisitor(FlatMappingVisitor out) { this.next = out; diff --git a/src/main/java/net/fabricmc/mappingio/adapter/ForwardingMappingVisitor.java b/src/main/java/net/fabricmc/mappingio/adapter/ForwardingMappingVisitor.java index 962dc888..876f9df1 100644 --- a/src/main/java/net/fabricmc/mappingio/adapter/ForwardingMappingVisitor.java +++ b/src/main/java/net/fabricmc/mappingio/adapter/ForwardingMappingVisitor.java @@ -27,6 +27,11 @@ import net.fabricmc.mappingio.MappingFlag; import net.fabricmc.mappingio.MappingVisitor; +/** + * A mapping visitor that forwards all visit calls to another {@link MappingVisitor}. + * + *

Subclasses should override the visit methods they want to intercept. + */ public abstract class ForwardingMappingVisitor implements MappingVisitor { protected ForwardingMappingVisitor(MappingVisitor next) { Objects.requireNonNull(next, "null next"); diff --git a/src/main/java/net/fabricmc/mappingio/adapter/MappingDstNsReorder.java b/src/main/java/net/fabricmc/mappingio/adapter/MappingDstNsReorder.java index b0232d25..c7317475 100644 --- a/src/main/java/net/fabricmc/mappingio/adapter/MappingDstNsReorder.java +++ b/src/main/java/net/fabricmc/mappingio/adapter/MappingDstNsReorder.java @@ -24,7 +24,15 @@ import net.fabricmc.mappingio.MappedElementKind; import net.fabricmc.mappingio.MappingVisitor; +/** + * A mapping visitor that reorders and/or drops destination namespaces. + */ public final class MappingDstNsReorder extends ForwardingMappingVisitor { + /** + * @param next The next visitor to forward the data to. + * @param newDstNs The destination namespaces, in the desired order. + * Omitting entries from the list is going to drop them. + */ public MappingDstNsReorder(MappingVisitor next, List newDstNs) { super(next); @@ -33,6 +41,11 @@ public MappingDstNsReorder(MappingVisitor next, List newDstNs) { this.newDstNs = newDstNs; } + /** + * @param next The next visitor to forward the data to + * @param newDstNs The destination namespaces, in the desired order. + * Omitting entries from the list is going to drop them. + */ public MappingDstNsReorder(MappingVisitor next, String... newDstNs) { this(next, Arrays.asList(newDstNs)); } diff --git a/src/main/java/net/fabricmc/mappingio/adapter/MappingNsCompleter.java b/src/main/java/net/fabricmc/mappingio/adapter/MappingNsCompleter.java index 90bf35d2..18472b42 100644 --- a/src/main/java/net/fabricmc/mappingio/adapter/MappingNsCompleter.java +++ b/src/main/java/net/fabricmc/mappingio/adapter/MappingNsCompleter.java @@ -27,11 +27,26 @@ import net.fabricmc.mappingio.MappedElementKind; import net.fabricmc.mappingio.MappingVisitor; +/** + * A mapping visitor that completes missing destination names. + * + *

Some mapping formats allow omitting destination names if equal to the source name. + * This visitor fills in these "holes" by copying names from another namespace. + */ public final class MappingNsCompleter extends ForwardingMappingVisitor { + /** + * @param next The next visitor to forward the data to. + * @param alternatives A map of which namespaces should copy from which others. + */ public MappingNsCompleter(MappingVisitor next, Map alternatives) { this(next, alternatives, false); } + /** + * @param next The next visitor to forward the data to. + * @param alternatives A map of which namespaces should copy from which others. + * @param addMissingNs Whether or not to copy namespaces from the alternatives keyset if not already present. + */ public MappingNsCompleter(MappingVisitor next, Map alternatives, boolean addMissingNs) { super(next); diff --git a/src/main/java/net/fabricmc/mappingio/adapter/MappingNsRenamer.java b/src/main/java/net/fabricmc/mappingio/adapter/MappingNsRenamer.java index a72de16c..48604b9a 100644 --- a/src/main/java/net/fabricmc/mappingio/adapter/MappingNsRenamer.java +++ b/src/main/java/net/fabricmc/mappingio/adapter/MappingNsRenamer.java @@ -24,7 +24,14 @@ import net.fabricmc.mappingio.MappingVisitor; +/** + * A mapping visitor that renames namespaces. + */ public final class MappingNsRenamer extends ForwardingMappingVisitor { + /** + * @param next The next visitor to forward the data to. + * @param nameMap A map of which namespaces should be renamed to which new names. + */ public MappingNsRenamer(MappingVisitor next, Map nameMap) { super(next); diff --git a/src/main/java/net/fabricmc/mappingio/adapter/MappingSourceNsSwitch.java b/src/main/java/net/fabricmc/mappingio/adapter/MappingSourceNsSwitch.java index fb931c63..991bbc32 100644 --- a/src/main/java/net/fabricmc/mappingio/adapter/MappingSourceNsSwitch.java +++ b/src/main/java/net/fabricmc/mappingio/adapter/MappingSourceNsSwitch.java @@ -52,9 +52,9 @@ public MappingSourceNsSwitch(MappingVisitor next, String newSourceNs) { /** * Create a new MappingSourceNsSwitch instance. * - * @param next MappingVisitor to pass the output to - * @param newSourceNs namespace to use for the new source name - * @param dropMissingNewSrcName whether to drop elements without a name in newSourceNs, will use original srcName otherwise + * @param next MappingVisitor to pass the output to. + * @param newSourceNs Namespace to use for the new source name. + * @param dropMissingNewSrcName Whether to drop elements without a name in newSourceNs, will use original srcName otherwise. */ public MappingSourceNsSwitch(MappingVisitor next, String newSourceNs, boolean dropMissingNewSrcName) { super(next); diff --git a/src/main/java/net/fabricmc/mappingio/adapter/MissingDescFilter.java b/src/main/java/net/fabricmc/mappingio/adapter/MissingDescFilter.java index 760afd2b..16929851 100644 --- a/src/main/java/net/fabricmc/mappingio/adapter/MissingDescFilter.java +++ b/src/main/java/net/fabricmc/mappingio/adapter/MissingDescFilter.java @@ -22,6 +22,9 @@ import net.fabricmc.mappingio.MappingVisitor; +/** + * A mapping visitor that filters out elements with missing source descriptors. + */ public final class MissingDescFilter extends ForwardingMappingVisitor { public MissingDescFilter(MappingVisitor next) { super(next); diff --git a/src/main/java/net/fabricmc/mappingio/adapter/RegularAsFlatMappingVisitor.java b/src/main/java/net/fabricmc/mappingio/adapter/RegularAsFlatMappingVisitor.java index 6dc8b0fb..0e9abba6 100644 --- a/src/main/java/net/fabricmc/mappingio/adapter/RegularAsFlatMappingVisitor.java +++ b/src/main/java/net/fabricmc/mappingio/adapter/RegularAsFlatMappingVisitor.java @@ -27,6 +27,9 @@ import net.fabricmc.mappingio.MappingFlag; import net.fabricmc.mappingio.MappingVisitor; +/** + * A {@link FlatMappingVisitor} that forwards all relevant data to a regular {@link MappingVisitor}. + */ public final class RegularAsFlatMappingVisitor implements FlatMappingVisitor { public RegularAsFlatMappingVisitor(MappingVisitor next) { this.next = next; diff --git a/src/main/java/net/fabricmc/mappingio/format/ColumnFileReader.java b/src/main/java/net/fabricmc/mappingio/format/ColumnFileReader.java index 17fb1077..8b3b996a 100644 --- a/src/main/java/net/fabricmc/mappingio/format/ColumnFileReader.java +++ b/src/main/java/net/fabricmc/mappingio/format/ColumnFileReader.java @@ -26,6 +26,9 @@ import net.fabricmc.mappingio.format.tiny.Tiny2Util; +/** + * Reader for column-based files. + */ @ApiStatus.Internal public final class ColumnFileReader implements Closeable { public ColumnFileReader(Reader reader, char columnSeparator) { @@ -43,9 +46,8 @@ public void close() throws IOException { * *

The reader will point to the next column or end of line if successful, otherwise remains unchanged. * - * @param expect content to expect - * @return true if the column was read and had the expected content, false otherwise - * @throws IOException + * @param expect Content to expect. + * @return {@code true} if the column was read and had the expected content, false otherwise. */ public boolean nextCol(String expect) throws IOException { if (eol) return false; diff --git a/src/main/java/net/fabricmc/mappingio/format/MappingFormat.java b/src/main/java/net/fabricmc/mappingio/format/MappingFormat.java index f0fa135e..c81e5249 100644 --- a/src/main/java/net/fabricmc/mappingio/format/MappingFormat.java +++ b/src/main/java/net/fabricmc/mappingio/format/MappingFormat.java @@ -33,16 +33,16 @@ * * Tiny v1 * ✔ - * ✔ - * ✖ - * ✖ - * ✖ + * src + * - + * - + * - * ✔ (Currently limited support) * * * Tiny v2 * ✔ - * ✔ + * src * ✔ * ✔ * ✔ @@ -50,57 +50,57 @@ * * * Enigma - * ✖ - * ✔ + * - + * src * ✔ * ✔ - * ✖ - * ✖ + * - + * - * * * SRG - * ✖ - * ✖ - * ✖ - * ✖ - * ✖ - * ✖ + * - + * - + * - + * - + * - + * - * * * XSRG - * ✖ - * ✔ - * ✖ - * ✖ - * ✖ - * ✖ + * - + * src & dst + * - + * - + * - + * - * * * CSRG/TSRG - * ✖ - * ✖ - * ✖ - * ✖ - * ✖ - * ✖ + * - + * - + * - + * - + * - + * - * * * TSRG2 * ✔ + * src + * - * ✔ - * ✖ - * ✔ - * ✖ - * ✖ + * - + * - * * * ProGuard - * ✖ - * ✔ - * ✖ - * ✖ - * ✖ - * ✖ + * - + * src + * - + * - + * - + * - * * */ @@ -127,23 +127,23 @@ public enum MappingFormat { ENIGMA_DIR("Enigma directory", null, false, true, true, true, false), /** - * The {@code SRG} ({@code Searge RetroGuard}) mapping format, as specified here. + * The {@code SRG} ("Searge RetroGuard") mapping format, as specified here. */ SRG_FILE("SRG file", "srg", false, false, false, false, false), /** - * The {@code XSRG} ({@code Extended SRG}) mapping format, as specified here. - * Same as SRG, but with field descriptors.. + * The {@code XSRG} ("Extended SRG") mapping format, as specified here. + * Same as SRG, but with field descriptors. */ XSRG_FILE("XSRG file", "xsrg", false, true, false, false, false), /** - * The {@code CSRG} ({@code Compact SRG}, since it saves disk space over SRG) mapping format, as specified here. + * The {@code CSRG} ("Compact SRG", since it saves disk space over SRG) mapping format, as specified here. */ CSRG_FILE("CSRG file", "csrg", false, false, false, false, false), /** - * The {@code TSRG} ({@code Tiny SRG}, since it saves disk space over SRG) mapping format, as specified here. + * The {@code TSRG} ("Tiny SRG", since it saves disk space over SRG) mapping format, as specified here. * Same as CSRG, but hierarchical instead of flat. */ TSRG_FILE("TSRG file", "tsrg", false, false, false, false, false), diff --git a/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaDirReader.java b/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaDirReader.java index eeb404f1..376a50d8 100644 --- a/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaDirReader.java +++ b/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaDirReader.java @@ -33,6 +33,12 @@ import net.fabricmc.mappingio.tree.MappingTree; import net.fabricmc.mappingio.tree.MemoryMappingTree; +/** + * {@linkplain MappingFormat#ENIGMA_DIRECTORY Enigma directory} reader. + * + *

Crashes if a second visit pass is requested without + * {@link MappingFlag#NEEDS_MULTIPLE_PASSES} having been passed beforehand. + */ public final class EnigmaDirReader { private EnigmaDirReader() { } diff --git a/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaDirWriter.java b/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaDirWriter.java index 4a2cb3b3..4a5aa2a6 100644 --- a/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaDirWriter.java +++ b/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaDirWriter.java @@ -31,6 +31,9 @@ import net.fabricmc.mappingio.MappedElementKind; import net.fabricmc.mappingio.format.MappingFormat; +/** + * {@linkplain MappingFormat#ENIGMA_DIRECTORY Enigma directory} writer. + */ public final class EnigmaDirWriter extends EnigmaWriterBase { public EnigmaDirWriter(Path dir, boolean deleteExistingFiles) throws IOException { super(null); diff --git a/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaFileReader.java b/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaFileReader.java index cafb1811..276dace1 100644 --- a/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaFileReader.java +++ b/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaFileReader.java @@ -26,9 +26,16 @@ import net.fabricmc.mappingio.MappingUtil; import net.fabricmc.mappingio.MappingVisitor; import net.fabricmc.mappingio.format.ColumnFileReader; +import net.fabricmc.mappingio.format.MappingFormat; import net.fabricmc.mappingio.tree.MappingTree; import net.fabricmc.mappingio.tree.MemoryMappingTree; +/** + * {@linkplain MappingFormat#ENIGMA_FILE Enigma file} reader. + * + *

Crashes if a second visit pass is requested without + * {@link MappingFlag#NEEDS_MULTIPLE_PASSES} having been passed beforehand. + */ public final class EnigmaFileReader { private EnigmaFileReader() { } diff --git a/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaFileWriter.java b/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaFileWriter.java index 4c285707..bc920c37 100644 --- a/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaFileWriter.java +++ b/src/main/java/net/fabricmc/mappingio/format/enigma/EnigmaFileWriter.java @@ -20,7 +20,11 @@ import java.io.Writer; import net.fabricmc.mappingio.MappedElementKind; +import net.fabricmc.mappingio.format.MappingFormat; +/** + * {@linkplain MappingFormat#ENIGMA_FILE Enigma file} writer. + */ public final class EnigmaFileWriter extends EnigmaWriterBase { public EnigmaFileWriter(Writer writer) throws IOException { super(writer); diff --git a/src/main/java/net/fabricmc/mappingio/format/proguard/ProGuardFileReader.java b/src/main/java/net/fabricmc/mappingio/format/proguard/ProGuardFileReader.java index d1670b7d..e2d8ea02 100644 --- a/src/main/java/net/fabricmc/mappingio/format/proguard/ProGuardFileReader.java +++ b/src/main/java/net/fabricmc/mappingio/format/proguard/ProGuardFileReader.java @@ -27,7 +27,14 @@ import net.fabricmc.mappingio.MappingFlag; import net.fabricmc.mappingio.MappingUtil; import net.fabricmc.mappingio.MappingVisitor; +import net.fabricmc.mappingio.format.MappingFormat; +/** + * {@linkplain MappingFormat#PROGUARD_FILE ProGuard file} reader. + * + *

Crashes if a second visit pass is requested without + * {@link MappingFlag#NEEDS_MULTIPLE_PASSES} having been passed beforehand. + */ public final class ProGuardFileReader { private ProGuardFileReader() { } diff --git a/src/main/java/net/fabricmc/mappingio/format/proguard/ProGuardFileWriter.java b/src/main/java/net/fabricmc/mappingio/format/proguard/ProGuardFileWriter.java index b566f930..e20d518a 100644 --- a/src/main/java/net/fabricmc/mappingio/format/proguard/ProGuardFileWriter.java +++ b/src/main/java/net/fabricmc/mappingio/format/proguard/ProGuardFileWriter.java @@ -26,14 +26,10 @@ import net.fabricmc.mappingio.MappedElementKind; import net.fabricmc.mappingio.MappingWriter; +import net.fabricmc.mappingio.format.MappingFormat; /** - * A mapping writer for the ProGuard mapping format. - * Note that this format is very basic: it only supports - * one namespace pair and only classes, methods and fields - * without comments. - * - * @see Official format documentation + * {@linkplain MappingFormat#PROGUARD_FILE ProGuard file} writer. */ public final class ProGuardFileWriter implements MappingWriter { private final Writer writer; @@ -44,7 +40,7 @@ public final class ProGuardFileWriter implements MappingWriter { * Constructs a ProGuard mapping writer that uses * the first destination namespace (index 0). * - * @param writer the writer where the mappings will be written + * @param writer The writer where the mappings will be written. */ public ProGuardFileWriter(Writer writer) { this(writer, 0); @@ -53,8 +49,8 @@ public ProGuardFileWriter(Writer writer) { /** * Constructs a ProGuard mapping writer. * - * @param writer the writer where the mappings will be written - * @param dstNamespace the namespace index to write as the destination namespace, must be at least 0 + * @param writer The writer where the mappings will be written. + * @param dstNamespace The namespace index to write as the destination namespace, must be at least 0. */ public ProGuardFileWriter(Writer writer, int dstNamespace) { this.writer = Objects.requireNonNull(writer, "writer cannot be null"); @@ -69,8 +65,8 @@ public ProGuardFileWriter(Writer writer, int dstNamespace) { /** * Constructs a ProGuard mapping writer. * - * @param writer the writer where the mappings will be written - * @param dstNamespace the namespace name to write as the destination namespace + * @param writer The writer where the mappings will be written. + * @param dstNamespace The namespace name to write as the destination namespace. */ public ProGuardFileWriter(Writer writer, String dstNamespace) { this.writer = Objects.requireNonNull(writer, "writer cannot be null"); @@ -79,8 +75,6 @@ public ProGuardFileWriter(Writer writer, String dstNamespace) { /** * Closes the internal {@link Writer}. - * - * @throws IOException if an IO error occurs */ @Override public void close() throws IOException { diff --git a/src/main/java/net/fabricmc/mappingio/format/srg/SrgFileReader.java b/src/main/java/net/fabricmc/mappingio/format/srg/SrgFileReader.java index 8fe35146..912fc6a7 100644 --- a/src/main/java/net/fabricmc/mappingio/format/srg/SrgFileReader.java +++ b/src/main/java/net/fabricmc/mappingio/format/srg/SrgFileReader.java @@ -30,6 +30,13 @@ import net.fabricmc.mappingio.tree.MappingTree; import net.fabricmc.mappingio.tree.MemoryMappingTree; +/** + * {@linkplain MappingFormat#SRG_FILE SRG file} and + * {@linkplain MappingFormat#XSRG_FILE XSRG file} reader. + * + *

Crashes if a second visit pass is requested without + * {@link MappingFlag#NEEDS_MULTIPLE_PASSES} having been passed beforehand. + */ public final class SrgFileReader { private SrgFileReader() { } diff --git a/src/main/java/net/fabricmc/mappingio/format/srg/SrgFileWriter.java b/src/main/java/net/fabricmc/mappingio/format/srg/SrgFileWriter.java index d7db765c..f6379a7d 100644 --- a/src/main/java/net/fabricmc/mappingio/format/srg/SrgFileWriter.java +++ b/src/main/java/net/fabricmc/mappingio/format/srg/SrgFileWriter.java @@ -28,6 +28,10 @@ import net.fabricmc.mappingio.MappingFlag; import net.fabricmc.mappingio.MappingWriter; +/** + * {@linkplain net.fabricmc.mappingio.format.MappingFormat#SRG_FILE SRG file} and + * {@linkplain net.fabricmc.mappingio.format.MappingFormat#XSRG_FILE XSRG file} writer. + */ public final class SrgFileWriter implements MappingWriter { public SrgFileWriter(Writer writer, boolean xsrg) { this.writer = writer; diff --git a/src/main/java/net/fabricmc/mappingio/format/srg/TsrgFileReader.java b/src/main/java/net/fabricmc/mappingio/format/srg/TsrgFileReader.java index 59582b07..dec67e7a 100644 --- a/src/main/java/net/fabricmc/mappingio/format/srg/TsrgFileReader.java +++ b/src/main/java/net/fabricmc/mappingio/format/srg/TsrgFileReader.java @@ -31,6 +31,14 @@ import net.fabricmc.mappingio.format.ColumnFileReader; import net.fabricmc.mappingio.format.MappingFormat; +/** + * {@linkplain MappingFormat#CSRG_FILE CSRG file}, + * {@linkplain MappingFormat#TSRG_FILE TSRG file} and + * {@linkplain MappingFormat#TSRG_2_FILE TSRG2 file} reader. + * + *

Crashes if a second visit pass is requested without + * {@link MappingFlag#NEEDS_MULTIPLE_PASSES} having been passed beforehand. + */ public final class TsrgFileReader { private TsrgFileReader() { } diff --git a/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny1FileReader.java b/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny1FileReader.java index d0ddcc36..f74f7f7b 100644 --- a/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny1FileReader.java +++ b/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny1FileReader.java @@ -26,9 +26,16 @@ import net.fabricmc.mappingio.MappingFlag; import net.fabricmc.mappingio.MappingVisitor; import net.fabricmc.mappingio.format.ColumnFileReader; +import net.fabricmc.mappingio.format.MappingFormat; import net.fabricmc.mappingio.tree.MappingTree; import net.fabricmc.mappingio.tree.MemoryMappingTree; +/** + * {@linkplain MappingFormat#TINY_1 Tiny v1 file} reader. + * + *

Crashes if a second visit pass is requested without + * {@link MappingFlag#NEEDS_MULTIPLE_PASSES} having been passed beforehand. + */ public final class Tiny1FileReader { private Tiny1FileReader() { } diff --git a/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny1FileWriter.java b/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny1FileWriter.java index 54575acd..f419e3ef 100644 --- a/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny1FileWriter.java +++ b/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny1FileWriter.java @@ -28,7 +28,11 @@ import net.fabricmc.mappingio.MappedElementKind; import net.fabricmc.mappingio.MappingFlag; import net.fabricmc.mappingio.MappingWriter; +import net.fabricmc.mappingio.format.MappingFormat; +/** + * {@linkplain MappingFormat#TINY_1 Tiny v1 file} writer. + */ public final class Tiny1FileWriter implements MappingWriter { public Tiny1FileWriter(Writer writer) { this.writer = writer; diff --git a/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny2FileReader.java b/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny2FileReader.java index 6381d80f..be4b408b 100644 --- a/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny2FileReader.java +++ b/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny2FileReader.java @@ -25,7 +25,14 @@ import net.fabricmc.mappingio.MappingFlag; import net.fabricmc.mappingio.MappingVisitor; import net.fabricmc.mappingio.format.ColumnFileReader; +import net.fabricmc.mappingio.format.MappingFormat; +/** + * {@linkplain MappingFormat#TINY_2 Tiny v2 file} reader. + * + *

Crashes if a second visit pass is requested without + * {@link MappingFlag#NEEDS_MULTIPLE_PASSES} having been passed beforehand. + */ public final class Tiny2FileReader { private Tiny2FileReader() { } diff --git a/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny2FileWriter.java b/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny2FileWriter.java index f2a14b0c..f2b5b017 100644 --- a/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny2FileWriter.java +++ b/src/main/java/net/fabricmc/mappingio/format/tiny/Tiny2FileWriter.java @@ -28,7 +28,11 @@ import net.fabricmc.mappingio.MappedElementKind; import net.fabricmc.mappingio.MappingFlag; import net.fabricmc.mappingio.MappingWriter; +import net.fabricmc.mappingio.format.MappingFormat; +/** + * {@linkplain MappingFormat#TINY_2 Tiny v2 file} writer. + */ public final class Tiny2FileWriter implements MappingWriter { public Tiny2FileWriter(Writer writer, boolean escapeNames) { this.writer = writer; diff --git a/src/main/java/net/fabricmc/mappingio/tree/MappingTree.java b/src/main/java/net/fabricmc/mappingio/tree/MappingTree.java index 78b29bd9..df8db66d 100644 --- a/src/main/java/net/fabricmc/mappingio/tree/MappingTree.java +++ b/src/main/java/net/fabricmc/mappingio/tree/MappingTree.java @@ -21,6 +21,9 @@ import org.jetbrains.annotations.Nullable; +/** + * Mutable mapping tree. + */ public interface MappingTree extends MappingTreeView { @Nullable String setSrcNamespace(String namespace); @@ -45,6 +48,7 @@ public interface MappingTree extends MappingTreeView { /** * Removes all metadata entries whose key is equal to the passed one. + * * @return Whether or not any entries have been removed. */ boolean removeMetadata(String key); diff --git a/src/main/java/net/fabricmc/mappingio/tree/MappingTreeView.java b/src/main/java/net/fabricmc/mappingio/tree/MappingTreeView.java index b9665e1e..d6f3eac4 100644 --- a/src/main/java/net/fabricmc/mappingio/tree/MappingTreeView.java +++ b/src/main/java/net/fabricmc/mappingio/tree/MappingTreeView.java @@ -24,6 +24,9 @@ import net.fabricmc.mappingio.MappingVisitor; +/** + * Read-only mapping tree. + */ public interface MappingTreeView { /** * @return The source namespace, or {@code null} if the tree is uninitialized. @@ -38,14 +41,14 @@ public interface MappingTreeView { List getDstNamespaces(); /** - * Get the maximum available namespace ID (exclusive). + * @return The maximum available namespace ID (exclusive). */ default int getMaxNamespaceId() { return getDstNamespaces().size(); } /** - * Get the minimum available namespace ID (inclusive). + * @return The minimum available namespace ID (inclusive). */ default int getMinNamespaceId() { return MIN_NAMESPACE_ID; diff --git a/src/main/java/net/fabricmc/mappingio/tree/MemoryMappingTree.java b/src/main/java/net/fabricmc/mappingio/tree/MemoryMappingTree.java index 2836c320..fcf6829b 100644 --- a/src/main/java/net/fabricmc/mappingio/tree/MemoryMappingTree.java +++ b/src/main/java/net/fabricmc/mappingio/tree/MemoryMappingTree.java @@ -40,6 +40,9 @@ import net.fabricmc.mappingio.MappingFlag; import net.fabricmc.mappingio.MappingVisitor; +/** + * {@link VisitableMappingTree} implementation that stores all data in memory. + */ public final class MemoryMappingTree implements VisitableMappingTree { public MemoryMappingTree() { this(false); diff --git a/src/main/java/net/fabricmc/mappingio/tree/VisitableMappingTree.java b/src/main/java/net/fabricmc/mappingio/tree/VisitableMappingTree.java index 19272660..4e9b3a97 100644 --- a/src/main/java/net/fabricmc/mappingio/tree/VisitableMappingTree.java +++ b/src/main/java/net/fabricmc/mappingio/tree/VisitableMappingTree.java @@ -18,5 +18,8 @@ import net.fabricmc.mappingio.MappingVisitor; +/** + * {@link MappingTree} that can be visited. + */ public interface VisitableMappingTree extends MappingTree, MappingVisitor { }