Add Javadoc

core/src/main/java/io/github/almightysatan/slams/Context.java

@@ -23,9 +23,15 @@
 import org.jetbrains.annotations.Nullable;
 
 /**
- * Determines which language should be used and provides additional context for placeholders.
+ * Determines which language should be used and can be extended to provide additional context for placeholders.
  */
 public interface Context {
 
+    /**
+     * Returns the identifier of the language that should be used for this context. The default language is used in case
+     * this returns {@code null}.
+     *
+     * @return the identifier of the language that should be used for this context
+     */
     @Nullable String language();
 }

core/src/main/java/io/github/almightysatan/slams/InvalidTypeException.java

@@ -20,5 +20,9 @@
 
 package io.github.almightysatan.slams;
 
+/**
+ * Thrown if the type of an object loaded by a {@link LanguageParser} does not match its expected type. For example the
+ * {@link LanguageParser} loads a String when an array of Strings is required.
+ */
 public class InvalidTypeException extends RuntimeException {
 }

core/src/main/java/io/github/almightysatan/slams/LanguageParser.java

@@ -27,15 +27,44 @@
 import java.io.IOException;
 import java.util.Set;
 
+/**
+ * Loads messages
+ */
 public interface LanguageParser {
 
+    /**
+     * Loads messages and calls {@link Values#put} to map a value to its path. {@link Values#put} should only be called
+     * for paths that are an element of {@link Values#paths}. Values loaded by previous parsers can be accessed via
+     * {@link Values#get}. Paths are case-sensitive.
+     *
+     * @param values the {@link Values} object used to map values
+     * @throws IOException if an error occurs while loading messages
+     */
     void load(@NotNull Values values) throws IOException;
 
     interface Values {
+        /**
+         * Returns a {@link Set} containing all valid paths.
+         *
+         * @return a {@link Set} containing all valid paths
+         */
         @NotNull @Unmodifiable Set<@NotNull String> paths();
 
+        /**
+         * Returns the value mapped to a given path or {@code null} if the value does not exist or the path is invalid.
+         *
+         * @param key the path
+         * @return the value
+         */
         @Nullable Object get(@NotNull String key);
 
-        void put(@NotNull String key, @NotNull Object value);
+        /**
+         * Maps a given value to its given path. May be called multiple times for the same path.
+         *
+         * @param key the path
+         * @param value the value
+         * @throws IllegalArgumentException if the path is invalid (is not an element of {@link Values#paths})
+         */
+        void put(@NotNull String key, @NotNull Object value) throws IllegalArgumentException;
     }
 }

core/src/main/java/io/github/almightysatan/slams/Message.java

@@ -25,21 +25,58 @@
 
 import java.util.Objects;
 
+/**
+ * Represents a message. The value of a message is not necessarily a {@link String}. It could be a multidimensional
+ * array of Strings, some sort of Map, a MiniMessage Component or something completely different.
+ *
+ * @param <T> the type of this messages value
+ */
 public interface Message<T> {
 
+    /**
+     * The dotted path of this message.
+     *
+     * @return the path of this message
+     */
     @NotNull String path();
 
+    /**
+     * Replaces placeholders and returns the resulting value. Uses the given {@link Context Contexts} language.
+     *
+     * @param context the context
+     * @param placeholderResolver a {@link PlaceholderResolver} with additional {@link Placeholder Placeholders}
+     * @return the value
+     */
     @NotNull T value(@Nullable Context context, @NotNull PlaceholderResolver placeholderResolver);
 
+    /**
+     * Replaces placeholders and returns the resulting value. Uses the given {@link Context Contexts} language.
+     *
+     * @param context the context
+     * @param placeholderResolvers an array of {@link PlaceholderResolver} with additional
+     *                             {@link Placeholder Placeholders}
+     * @return the value
+     */
     default @NotNull T value(@Nullable Context context, @NotNull PlaceholderResolver @NotNull ... placeholderResolvers) {
         Objects.requireNonNull(placeholderResolvers);
         return this.value(context, PlaceholderResolver.of(placeholderResolvers));
     }
 
+    /**
+     * Replaces placeholders and returns the resulting value. Uses the given {@link Context Contexts} language.
+     *
+     * @param context the context
+     * @return the value
+     */
     default @NotNull T value(@Nullable Context context) {
         return this.value(context, PlaceholderResolver.empty());
     }
 
+    /**
+     * Replaces placeholders and returns the resulting value. Uses the default language.
+     *
+     * @return the value
+     */
     default @NotNull T value() {
         return this.value(null);
     }

core/src/main/java/io/github/almightysatan/slams/Placeholder.java

@@ -26,17 +26,41 @@
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * Represents a placeholder. Extends {@link PlaceholderResolver} as a placeholder can resolve itself.
+ *
+ * @see Placeholder#constant(String, String)
+ */
 public interface Placeholder extends PlaceholderResolver {
 
+    /**
+     * The key of this placeholder. This should always return the same value. A key should not be null or empty.
+     *
+     * @return the key
+     */
     @NotNull String key();
 
+    /**
+     * Evaluates the value of the placeholder using the given context and arguments.
+     *
+     * @param context the context
+     * @param arguments the arguments
+     * @return the value of this placeholder
+     */
     @NotNull String value(@Nullable Context context, @NotNull List<@NotNull String> arguments);
 
     @Override
     default @Nullable Placeholder resolve(@NotNull String key) {
         return key.equals(this.key()) ? this : null;
     }
 
+    /**
+     * Returns a new placeholder.
+     *
+     * @param key the placeholder's key
+     * @param valueFunction a function that evaluates this placeholder's value
+     * @return a new placeholder.
+     */
     static @NotNull Placeholder of(@NotNull String key, @NotNull ValueFunction valueFunction) {
         Objects.requireNonNull(key);
         Objects.requireNonNull(valueFunction);
@@ -53,14 +77,35 @@ public interface Placeholder extends PlaceholderResolver {
         };
     }
 
+    /**
+     * Returns a new placeholder. The {@link Context} is ignored when evaluating its value.
+     *
+     * @param key the placeholder's key
+     * @param valueFunction a function that evaluates this placeholder's value
+     * @return a new placeholder.
+     */
     static @NotNull Placeholder withArgs(@NotNull String key, @NotNull ContextIndependentValueFunction valueFunction) {
         return of(key, valueFunction);
     }
 
+    /**
+     * Returns a new placeholder. Arguments are ignored when evaluating its value.
+     *
+     * @param key the placeholder's key
+     * @param valueFunction a function that evaluates this placeholder's value
+     * @return a new placeholder.
+     */
     static @NotNull Placeholder withContext(@NotNull String key, @NotNull ArgumentIndependentValueFunction valueFunction) {
         return of(key, valueFunction);
     }
 
+    /**
+     * Returns a new placeholder with a constant value.
+     *
+     * @param key the placeholder's key
+     * @param value the value
+     * @return a new placeholder
+     */
     static @NotNull Placeholder constant(@NotNull String key, @NotNull String value) {
         Objects.requireNonNull(value);
         return of(key, (context, arguments) -> value);

core/src/main/java/io/github/almightysatan/slams/PlaceholderResolver.java

@@ -26,20 +26,48 @@
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * Resolves {@link Placeholder Placeholders}.
+ */
 @FunctionalInterface
 public interface PlaceholderResolver {
 
+    /**
+     * Searches for a {@link Placeholder} with the given key. SLAMS may cache the resulting {@link Placeholder} if
+     * possible.
+     *
+     * @param key the key
+     * @return the placeholder or {@code null}
+     */
     @Nullable Placeholder resolve(@NotNull String key);
 
+    /**
+     * Returns a {@link PlaceholderResolver} that always returns null (does not resolve any
+     * {@link Placeholder Placeholders}).
+     *
+     * @return a {@link PlaceholderResolver} that always returns null
+     */
     static @NotNull PlaceholderResolver empty() {
         return key -> null;
     }
 
+    /**
+     * Returns a {@link PlaceholderResolver} that only resolves a single {@link Placeholder}.
+     *
+     * @param placeholder the {@link Placeholder}
+     * @return a new {@link PlaceholderResolver}
+     */
     static @NotNull PlaceholderResolver of(@NotNull Placeholder placeholder) {
         Objects.requireNonNull(placeholder);
         return key -> key.equals(placeholder.key()) ? placeholder : null;
     }
 
+    /**
+     * Returns a {@link PlaceholderResolver} that can resolve all the given {@link Placeholder Placeholders}.
+     *
+     * @param placeholders an array of {@link Placeholder Placeholders}
+     * @return a new {@link PlaceholderResolver}
+     */
     static @NotNull PlaceholderResolver of(@NotNull Placeholder @NotNull ... placeholders) {
         if (placeholders.length == 0)
             return empty();
@@ -52,6 +80,14 @@ public interface PlaceholderResolver {
         };
     }
 
+    /**
+     * Returns a {@link PlaceholderResolver} that will use the given {@link PlaceholderResolver PlaceholderResolvers} to
+     * find a {@link Placeholder}. It can therefore resolve any {@link Placeholder} resolved by at least one of the
+     * given {@link PlaceholderResolver PlaceholderResolvers}.
+     *
+     * @param placeholderResolvers an array of {@link PlaceholderResolver PlaceholderResolvers}
+     * @return a new {@link PlaceholderResolver}
+     */
     static @NotNull PlaceholderResolver of(@NotNull PlaceholderResolver @NotNull ... placeholderResolvers) {
         if (placeholderResolvers.length == 0)
             return empty();
@@ -65,6 +101,14 @@ public interface PlaceholderResolver {
         };
     }
 
+    /**
+     * Returns a {@link PlaceholderResolver} that will use the given {@link PlaceholderResolver PlaceholderResolvers} to
+     * find a {@link Placeholder}. It can therefore resolve any {@link Placeholder} resolved by at least one of the
+     * given {@link PlaceholderResolver PlaceholderResolvers}.
+     *
+     * @param placeholderResolvers a list of {@link PlaceholderResolver PlaceholderResolvers}
+     * @return a new {@link PlaceholderResolver}
+     */
     static @NotNull PlaceholderResolver of(@NotNull List<@NotNull PlaceholderResolver> placeholderResolvers) {
         return of(placeholderResolvers.toArray(new PlaceholderResolver[0]));
     }

core/src/main/java/io/github/almightysatan/slams/Slams.java

@@ -26,16 +26,49 @@
 import java.io.IOException;
 import java.util.Collection;
 
+/**
+ * The main SLAMS object.
+ */
 public interface Slams {
 
-    void load(@NotNull String identifier, @NotNull LanguageParser... parsers) throws IOException;
+    /**
+     * Registers a new language with the given identifier and loads its messages using the given
+     * {@link LanguageParser LanguageParsers}. If more than one {@link LanguageParser} is supplied they will be run in
+     * sequential order and can read or overwrite values loaded by previous parsers.
+     *
+     * @param identifier the new languages identifier
+     * @param parsers the {@link LanguageParser LanguageParsers} that should be used to load messages
+     * @throws IOException if a parser throws an exception
+     */
+    void load(@NotNull String identifier, @NotNull LanguageParser @NotNull ... parsers) throws IOException;
 
+    /**
+     * Reloads all languages.
+     *
+     * @throws IOException if a parser throws an exception
+     */
     void reload() throws IOException;
 
+    /**
+     * Returns a {@link Collection} containing the identifiers of all registered languages.
+     *
+     * @return a {@link Collection} containing the identifiers of all registered languages
+     */
     @NotNull Collection<@NotNull String> languages();
 
+    /**
+     * Returns the identifier of the default language.
+     *
+     * @return the identifier of the default language
+     */
     @NotNull String defaultLanguageIdentifier();
 
+    /**
+     * Creates a new {@link Slams} instance.
+     *
+     * @param defaultLanguageIdentifier the identifier of the default language
+     * @return a new {@link Slams} instance
+     */
     static Slams create(@NotNull String defaultLanguageIdentifier) {
         return new SlamsImpl(defaultLanguageIdentifier);
     }

minimessage/src/main/java/io/github/almightysatan/slams/minimessage/AdventureGenericMessage.java

@@ -29,10 +29,29 @@
 
 import java.util.Objects;
 
+/**
+ * Represents a MiniMessage {@link Message}.
+ *
+ * @param <T> the type of this messages value
+ */
 public interface AdventureGenericMessage<T> extends Message<T> {
 
+    /**
+     * Replaces placeholders and returns the resulting value. Uses the given {@link Context Contexts} language.
+     *
+     * @param context the context
+     * @param tagResolver a {@link TagResolver}
+     * @return the value
+     */
     @NotNull T value(@Nullable Context context, @NotNull TagResolver tagResolver);
 
+    /**
+     * Replaces placeholders and returns the resulting value. Uses the given {@link Context Contexts} language.
+     *
+     * @param context the context
+     * @param tagResolvers an array of {@link TagResolver TagResolvers}
+     * @return the value
+     */
     default @NotNull T value(@Nullable Context context, @NotNull TagResolver @NotNull ... tagResolvers) {
         Objects.requireNonNull(tagResolvers);
         return this.value(context, ContextTagResolver.of(tagResolvers));

minimessage/src/main/java/io/github/almightysatan/slams/minimessage/AdventureMessage.java

@@ -38,12 +38,11 @@ public interface AdventureMessage extends AdventureGenericMessage<Component> {
 
     /**
      * Creates a new {@link AdventureMessage} with the given path, {@link Slams} and {@link ContextTagResolver}.
-     * If
      *
      * @param path        the path of the entry
      * @param slams       the language manager (slams instance) to use
      * @param tagResolver the tag resolver
-     * @return the created entry
+     * @return a new {@link AdventureMessage}
      */
     static @NotNull AdventureMessage of(@NotNull String path, @NotNull Slams slams, @NotNull TagResolver tagResolver) {
         class AdventureMessageImpl extends MessageImpl<Component, String, TagResolver> implements AdventureMessage {
@@ -75,6 +74,13 @@ protected AdventureMessageImpl(@NotNull String path, @NotNull Slams languageMana
         return new AdventureMessageImpl(path, slams, tagResolver);
     }
 
+    /**
+     * Creates a new {@link AdventureMessage} with the given path.
+     *
+     * @param path        the path of the entry
+     * @param slams       the language manager (slams instance) to use
+     * @return a new {@link AdventureMessage}
+     */
     static @NotNull AdventureMessage of(@NotNull String path, @NotNull Slams slams) {
         return of(path, slams, TagResolver.empty());
     }