Add project scaladoc

Signed-off-by: Iltotore <rafbodaha@gmail.com>

example/src/main/scala/io/github/iltotore/scala/spigot/example/Main.scala

@@ -1,18 +1,13 @@
 package io.github.iltotore.scala.spigot.example
 
 import io.github.iltotore.scala.spigot.Implicits._
-import io.github.iltotore.scala.spigot.factory
-import io.github.iltotore.scala.spigot.factory.Player
-import org.bukkit.entity.Slime
-import org.bukkit.inventory.EquipmentSlot
+import io.github.iltotore.scala.spigot.scheduler.SpigotRunnable
 import org.bukkit.plugin.java.JavaPlugin
 
 object Main extends JavaPlugin {
 
   implicit val implicitReference: JavaPlugin = this
 
   override def onEnable(): Unit = {
-    "sec" ~> null
-    factory.World("").spawnGeneric[Slime](null)
   }
 }

src/main/scala/io/github/iltotore/scala/spigot/Implicits.scala

@@ -2,60 +2,138 @@ package io.github.iltotore.scala.spigot
 
 import java.util
 
-import org.bukkit.block.data.BlockData
 import org.bukkit.block.{Block, BlockState}
 import org.bukkit.command.CommandExecutor
-import org.bukkit.entity.{Entity, Item}
+import org.bukkit.entity.Entity
 import org.bukkit.inventory.meta.ItemMeta
 import org.bukkit.inventory.{EntityEquipment, EquipmentSlot, Inventory, ItemStack}
-import org.bukkit.material.MaterialData
 import org.bukkit.plugin.java.JavaPlugin
-import org.bukkit.scoreboard.{Objective, Score}
+import org.bukkit.scoreboard.Objective
 import org.bukkit.util.Vector
 import org.bukkit.{ChatColor, Location, World}
 
 import scala.reflect.ClassTag
+import scala.util.Try
 
+/**
+ * Contains implicit decorators classes.
+ */
 object Implicits {
 
   implicit class StringDecorator(base: String) {
 
+    /**
+     * Color the wrapped String using ChatColor.translateAlternatesColors.
+     *
+     * @param char the used char. Default: &.
+     * @return a colored version of this String.
+     */
     def color(char: Char = '&'): String = ChatColor.translateAlternateColorCodes(char, base)
   }
 
   implicit class InventoryDecorator(base: Inventory) {
 
+    /**
+     * Operator alias of Inventory#addItem
+     *
+     * @param item the ItemStack to add.
+     * @return the wrapped Inventory content as HashMap[Integer, ItemStack]
+     */
     def +=(item: ItemStack): util.HashMap[Integer, ItemStack] = base.addItem(item)
 
+    /**
+     * Operator alias of Inventory#setItem
+     *
+     * @param index the index to set.
+     * @param item  the added ItemStack.
+     */
     def update(index: Int, item: ItemStack): Unit = base.setItem(index, item)
 
-    def apply(index: Int): ItemStack = base.getItem(index)
+    /**
+     * Get the ItemStack contained by the given slot.
+     *
+     * @param index the slot index.
+     * @return an Optional potentially containing the held ItemStack.
+     */
+    def apply(index: Int): Option[ItemStack] = Option(base.getItem(index))
   }
 
   implicit class WorldDecorator(base: World) {
 
+    /**
+     * Alias of World#getBlockAt.
+     *
+     * @param loc the Location of the wanted Block.
+     * @return the Block at is Location.
+     */
     def apply(loc: Location): Block = base.getBlockAt(loc)
 
+    /**
+     * Alias of World#getBlockAt.
+     *
+     * @param x the x coordinate.
+     * @param y the y coordinate.
+     * @param z the z coordinate.
+     * @return the Block at the given coordinates.
+     */
     def apply(x: Int, y: Int, z: Int): Block = base.getBlockAt(x, y, z)
 
+    /**
+     * A classless wrapper of World#spawn.
+     *
+     * @param loc the location where the entity will be spawned.
+     * @param tag the implicit tag passed by the T generic type. Used to retrieve the entity class.
+     * @tparam T the entity type to spawn.
+     * @return the newly created entity.
+     */
     def spawnGeneric[T <: Entity: ClassTag](loc: Location)(implicit tag: ClassTag[T]): T =
       base.spawn(loc, tag.runtimeClass.asInstanceOf[Class[T]])
 
-    def getEntitiesByGeneric[T <: Entity: ClassTag](loc: Location)(implicit tag: ClassTag[T]): util.Collection[T] =
+    /**
+     * A classless wrapper of World#getEntitiesByClass.
+     *
+     * @param tag the implicit tag passed by the T generic type. Used to retrieve the entity class.
+     * @tparam T the wanted entity type.
+     * @return a collection of entities matching with the given type.
+     */
+    def getEntitiesOfType[T <: Entity: ClassTag](implicit tag: ClassTag[T]): util.Collection[T] =
       base.getEntitiesByClass(tag.runtimeClass.asInstanceOf[Class[T]])
   }
 
   implicit class CommandAssignment(name: String)(implicit plugin: JavaPlugin) {
+
+    /**
+     * Set the executor of the given command represented by his name.
+     *
+     * @param executor the command executor.
+     */
     def ~>(executor: CommandExecutor): Unit = plugin.getCommand(name).setExecutor(executor)
   }
 
   implicit class EquipmentDecorator(base: EntityEquipment) {
 
-    def apply(slot: EquipmentSlot): ItemStack = base.getItem(slot)
-
+    /**
+     * Alias of EntityEquipment#getItem.
+     *
+     * @param slot the EquipmentSlot to get at.
+     * @return an Option containing the ItemStack at the given slot if exists.
+     */
+    def apply(slot: EquipmentSlot): Option[ItemStack] = Option(base.getItem(slot))
+
+    /**
+     * Alias of EntityEquipment#setItem.
+     *
+     * @param slot the EquipmentSlot to set at.
+     * @param item the ItemStack to set.
+     */
     def update(slot: EquipmentSlot, item: ItemStack): Unit = base.setItem(slot, item)
   }
 
+  /**
+   * A Simple wrapper of org.bukkit.Vector adding arithmetic aliases.
+   *
+   * @param base the decorated Vector.
+   */
   implicit class VectorArithmetic(base: Vector) {
 
     def +=(vector: Vector): Vector = base.add(vector)
@@ -69,6 +147,11 @@ object Implicits {
     def /=(vector: Vector): Vector = base.add(vector)
   }
 
+  /**
+   * A Simple wrapper of org.bukkit.Location adding arithmetic aliases.
+   *
+   * @param base the decorated Location.
+   */
   implicit class LocationDecorator(base: Location) {
 
     def +=(location: Location): Location = base.add(location)
@@ -84,18 +167,41 @@ object Implicits {
 
   implicit class BlockDecorator(base: Block) {
 
-    def getStateAs[T <: BlockState]: T = base.getState.asInstanceOf[T]
+    /**
+     * Get the wrapped Block's state and try to cast it.
+     *
+     * @tparam T the type to cast to.
+     * @return A Try[T] representing the attempt of casting the wanted BlockState.
+     */
+    def getStateAs[T <: BlockState]: Try[T] = Try(base.getState.asInstanceOf[T])
   }
 
   implicit class ItemDecorator(base: ItemStack) {
 
+    /**
+     * Get the wrapped item's metadata and try to cast it.
+     *
+     * @tparam T the type to cast to.
+     * @return A Try[T] representing the attempt of casting the wanted ItemMeta.
+     */
     def getItemMetaAs[T <: ItemMeta]: T = base.getItemMeta.asInstanceOf[T]
-
   }
 
   implicit class ObjectiveDecorator(base: Objective) {
 
+    /**
+     * Get the score of an entry for the wrapped Objective as Int.
+     * @param entry the entry to get score of.
+     * @return the score of the given entry for the wrapped Objective.
+     */
     def apply(entry: String): Int = base.getScore(entry).getScore
+
+    /**
+     * Set the score of an entry for the wrapped Objective.
+     * @param entry the entry to set score of.
+     * @param score the new score.
+     */
     def update(entry: String, score: Int): Unit = base.getScore(entry).setScore(score)
   }
+
 }

src/main/scala/io/github/iltotore/scala/spigot/scheduler/SpigotRunnable.scala

@@ -6,29 +6,49 @@ import org.bukkit.Bukkit
 import org.bukkit.plugin.Plugin
 import org.bukkit.scheduler.BukkitTask
 
+/**
+ * A custom control structure wrapping org.bukkit.BukkitRunnable.
+ * @param consumer the executed method.
+ */
 class SpigotRunnable(consumer: BukkitTask => Unit) {
-  var delay = 0L
-  var interval = Option.empty[Long] //Option = Java's optionals. If defined, the produced Runnable will be run using runTaskTimer.
-
+  private var delay = 0L
+  private var interval = Option.empty[Long] //Option = Java's optionals. If defined, the produced Runnable will be run using runTaskTimer.
+
+  /**
+   * Set the "later" delay.
+   * @param delay the time in ticks to wait before running the task.
+   * @return this SpigotRunnable for chaining
+   */
   def after(delay: Long): SpigotRunnable = {
     this.delay = delay
     this //We return this instance for chaining.
   }
 
+  /**
+   * Set the time between each execution.
+   * @param interval the period in ticks between each execution.
+   * @return this SpigotRunnable for chaining
+   */
   def each(interval: Long): SpigotRunnable = {
     this.interval = Option(interval)
     this //The return keyword is not required at the last method line.
   }
 
-  //Launch the runnable and return the generated task.
+  /**
+   * Launch this SpigotRunnable.
+   * @param plugin the plugin used to schedule this SpigorRunnable
+   */
   def now(plugin: Plugin): Unit = interval match { //This is called pattern matching. Check A Tour of Scala's dedicated article ;)
     case Some(ticks) => Bukkit.getScheduler.runTaskTimer(plugin, consumer.asInstanceOf[Consumer[BukkitTask]], delay, ticks) //An Option can be an instance of Some or None.
 
     case None => Bukkit.getScheduler.runTaskLater(plugin, consumer.asInstanceOf[Consumer[BukkitTask]], delay)
   }
 }
 
+/**
+ * SpigotRunnable DSL's starting point
+ */
 object SpigotRunnable {
-  def apply(consumer: BukkitTask => Unit): SpigotRunnable = new SpigotRunnable(consumer)
-  def apply(runnable: => Unit):  SpigotRunnable = apply(_ => runnable)
+  def consumer(consumer: BukkitTask => Unit): SpigotRunnable = new SpigotRunnable(consumer)
+  def apply(runnable: => Unit):  SpigotRunnable = consumer(_ => runnable)
 }

src/main/scala/io/github/iltotore/scala/spigot/scheduler/SpigotTimer.scala

@@ -4,16 +4,14 @@ import org.bukkit.scheduler.BukkitTask
 
 object SpigotTimer {
 
-  def apply(time: Long)(consumer: BukkitTask => Unit):  SpigotRunnable = {
-    var t = time;
-    SpigotRunnable (task => {
+  def consumer(time: Long)(consumer: BukkitTask => Unit):  SpigotRunnable = {
+    var t = time
+    SpigotRunnable.consumer( task => {
       t-=1
       consumer(task)
       if(t <= 0) task.cancel()
     })
   }
 
-  object Runnable {
-    def apply(time: Long)(runnable: => Unit): SpigotRunnable = SpigotTimer(time)(_ => runnable)
-  }
+  def apply(time: Long)(runnable: => Unit): SpigotRunnable = consumer(time)(_ => runnable)
 }