docs: add missing Javadoc

src/etc/stork/stork.yml

@@ -35,7 +35,7 @@ max_java_memory: 512
 #min_java_memory_pct: 10
 #max_java_memory_pct: 20
 
-# Try to createVelocityToolManager a symbolic link to java executable in <app_home>/run with
+# Try to create a symbolic link to java executable in <app_home>/run with
 # the name of "<app_name>-java" so that commands like "ps" will make it
 # easier to find your app
 symlink_java: true

src/main/java/com/github/polpetta/mezzotre/i18n/LocalizedMessageFactory.java

@@ -12,6 +12,13 @@ import org.apache.velocity.tools.config.FactoryConfiguration;
 import org.apache.velocity.tools.config.ToolConfiguration;
 import org.apache.velocity.tools.config.ToolboxConfiguration;
 
+/**
+ * This class provides utility to create {@link ToolManager} for {@link VelocityEngine} or to
+ * retrieve simple localized strings from the system.
+ *
+ * @author Davide Polonio
+ * @since 1.0
+ */
 public class LocalizedMessageFactory {
 
   private final VelocityEngine velocityEngine;
@@ -21,6 +28,14 @@ public class LocalizedMessageFactory {
     this.velocityEngine = velocityEngine;
   }
 
+  /**
+   * Provide a {@link ToolManager} completely setup. Localization will be taken from jar resources,
+   * and {@link LocalizedTool} can be used in Velocity templates to automatically access them.
+   *
+   * @param locale the language needed
+   * @return a {@link ToolManager} ready with the desired locale, if it exists. Fallback to english
+   *     otherwise
+   */
   public ToolManager createVelocityToolManager(Locale locale) {
 
     final ToolManager toolManager = new ToolManager();
@@ -39,6 +54,12 @@ public class LocalizedMessageFactory {
     return toolManager;
   }
 
+  /**
+   * Creates a {@link ResourceBundle} object that can be used to access single localized strings
+   *
+   * @param locale the language desired to retrieve the translated strings
+   * @return a {@link ResourceBundle} with the provided locale
+   */
   public ResourceBundle createResourceBundle(Locale locale) {
     return ResourceBundle.getBundle("i18n/message", locale);
   }

src/main/java/com/github/polpetta/mezzotre/orm/model/CallbackQueryContext.java

@@ -28,6 +28,10 @@ public class CallbackQueryContext extends Base {
   @Length(36)
   private final String id;
 
+  /**
+   * Each callback can belong to a particular group. In that case, this variable will be the same
+   * for all the related {@link CallbackQueryMetadata}
+   */
   @NotNull
   @Length(36)
   private final String entryGroup;

src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/Dispatcher.java

@@ -11,6 +11,14 @@ import javax.inject.Inject;
 import javax.inject.Named;
 import javax.inject.Singleton;
 
+/**
+ * This class dispatches incoming {@link Update} containing a {@link
+ * com.pengrad.telegrambot.model.CallbackQuery} entry to the right {@link Processor} that will take
+ * care of processing them.
+ *
+ * @author Davide Polonio
+ * @since 1.0
+ */
 @Singleton
 public class Dispatcher {
 
@@ -25,6 +33,17 @@ public class Dispatcher {
     this.threadPool = threadPool;
   }
 
+  /**
+   * This method searches for the right {@link Processor} installed in the system. A {@link
+   * CallbackQueryContext} has to be previously saved in the database in order for this method to
+   * find the right event to process. Once the corresponding {@link Processor} is found, the
+   * computation is delegated to it
+   *
+   * @param callbackQueryContext the context coming from the database storage - cannot be null
+   * @param update the incoming {@link Update} coming from Telegram
+   * @return a {@link CompletableFuture} containing an {@link Optional} that may or not have a
+   *     {@link BaseRequest} response to send back to Telegram.
+   */
   public CompletableFuture<Optional<BaseRequest<?, ?>>> dispatch(
       CallbackQueryContext callbackQueryContext, Update update) {
     return CompletableFuture.completedFuture(update)

src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/EventProcessorNotFoundException.java

@@ -1,5 +1,11 @@
 package com.github.polpetta.mezzotre.telegram.callbackquery;
 
+/**
+ * Wrapper exception when a valid {@link Processor} is not found in the system
+ *
+ * @author Davide Polonio
+ * @since 1.0
+ */
 public class EventProcessorNotFoundException extends RuntimeException {
   public EventProcessorNotFoundException() {}
 

src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/Processor.java

@@ -6,9 +6,33 @@ import com.pengrad.telegrambot.request.BaseRequest;
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * A processor is an object which is able to process an incoming Telegram {@link Update} containing
+ * a {@link com.pengrad.telegrambot.model.CallbackQuery}. Any event of this type is related to a
+ * previous message.
+ *
+ * @author Davide Polonio
+ * @since 1.0
+ */
 public interface Processor {
+
+  /**
+   * The even name this processor is able to process
+   *
+   * @return a {@link String} containig the name of the event supported
+   */
   String getEventName();
 
+  /**
+   * Process the current event
+   *
+   * @param callbackQueryContext the corresponding even {@link CallbackQueryContext} previously
+   *     stored in the database
+   * @param update the Telegram {@link Update} containing a {@link
+   *     com.pengrad.telegrambot.model.CallbackQuery} incoming Telegram
+   * @return a {@link CompletableFuture} containing an {@link Optional} that may or maybe not have a
+   *     {@link BaseRequest}, that is the response that will be sent back to Telegram
+   */
   CompletableFuture<Optional<BaseRequest<?, ?>>> process(
       CallbackQueryContext callbackQueryContext, Update update);
 }