Improve PotionEffect(.Builder) javadocs (#2403)

* Improve PotionEffect(.Builder) javadocs

Fixes outright issues in some of the builder javadocs and elaborates on some non-obvious methods

* Further javadoc improvements/fixes

* Update ambient description & improve consistency

Author: qixils

src/main/java/org/spongepowered/api/effect/potion/PotionEffect.java

@@ -57,11 +57,12 @@ static Builder builder() {
      * duration in ticks.
      *
      * @param type The potion type
-     * @param amplifier The amplifier
+     * @param amplifier The zero-indexed amplifier
      * @param duration The duration in ticks
      * @return The potion effect
+     * @throws IllegalArgumentException If the amplifier is negative or the duration is not positive
      */
-    static PotionEffect of(PotionEffectType type, int amplifier, int duration) {
+    static PotionEffect of(PotionEffectType type, int amplifier, int duration) throws IllegalArgumentException {
         return PotionEffect.builder().potionType(type).amplifier(amplifier).duration(duration).build();
     }
 
@@ -74,8 +75,9 @@ static PotionEffect of(PotionEffectType type, int amplifier, int duration) {
      * @param amplifier The amplifier
      * @param duration The duration in ticks
      * @return The potion effect
+     * @throws IllegalArgumentException If the amplifier is negative or the duration is not positive
      */
-    static PotionEffect of(Supplier<? extends PotionEffectType> type, int amplifier, int duration) {
+    static PotionEffect of(Supplier<? extends PotionEffectType> type, int amplifier, int duration) throws IllegalArgumentException {
         return PotionEffect.builder().potionType(type).amplifier(amplifier).duration(duration).build();
     }
 
@@ -90,22 +92,23 @@ static PotionEffect of(Supplier<? extends PotionEffectType> type, int amplifier,
      * Gets the duration in ticks for which this potion effect
      * will apply for.
      *
-     * @return The duration.
+     * @return The duration in ticks.
      */
     int duration();
 
     /**
      * Gets the amplifier at which this potion effect
      * will apply effects.
      *
-     * @return The amplifier.
+     * @return The amplifier as a zero-indexed integer.
      */
     int amplifier();
 
     /**
-     * Gets if the potion effect is an ambient effect.
+     * Gets whether or not this potion effect is an ambient effect.
+     * Ambient potions emit more translucent particles.
      *
-     * @return Gets if ambient.
+     * @return If the effect should be ambient.
      */
     boolean isAmbient();
 
@@ -152,15 +155,18 @@ default Builder potionType(Supplier<? extends PotionEffectType> potionEffectType
         /**
          * Sets the duration in ticks of the potion effect.
          *
+         * <p>The duration must be greater than zero ticks.</p>
+         *
          * @param duration The duration in ticks of this effect
          * @return This builder, for chaining
+         * @throws IllegalArgumentException If the duration is less than or equal to zero
          */
-        Builder duration(int duration);
+        Builder duration(int duration) throws IllegalArgumentException;
 
         /**
          * Sets the amplifier power of the potion effect.
          *
-         * <p>Amplifiers must be above zero.</p>
+         * <p>Amplifiers must be greater than or equal to zero.</p>
          *
          * @param amplifier The amplifier power
          * @return This builder, for chaining
@@ -169,23 +175,24 @@ default Builder potionType(Supplier<? extends PotionEffectType> potionEffectType
         Builder amplifier(int amplifier) throws IllegalArgumentException;
 
         /**
-         * Sets the potion effect to be ambient or not.
+         * Sets whether the potion effect is ambient.
+         * Ambient potions emit more translucent particles.
          *
          * @param ambient Whether the potion effect is ambient
          * @return This builder, for chaining
          */
         Builder ambient(boolean ambient);
 
         /**
-         * Sets the potion effect to show particles when applied or not.
+         * Sets whether the potion effect should show particles when applied.
          *
          * @param showParticles Whether the potion effect will show particles
          * @return This builder, for chaining
          */
         Builder showParticles(boolean showParticles);
 
         /**
-         * Sets the potion effect to show its icon when applied or not.
+         * Sets whether the potion effect should show its icon when applied.
          *
          * @param showIcon Whether the potion effect will show its icon
          * @return This builder, for chaining