From cb2f7443f57b2e4e3ee8f8e2dd54b7a6e27e7b36 Mon Sep 17 00:00:00 2001
From: EpicKnarvik97 <kristian.knarvik@knett.no>
Date: Thu, 21 Oct 2021 16:39:35 +0200
Subject: [PATCH] Improves comments for PortalOptions

---
 .../stargate/portal/PortalOptions.java        | 37 ++++++++++++++++---
 1 file changed, 32 insertions(+), 5 deletions(-)

diff --git a/src/main/java/net/knarcraft/stargate/portal/PortalOptions.java b/src/main/java/net/knarcraft/stargate/portal/PortalOptions.java
index d2335e8..221fed7 100644
--- a/src/main/java/net/knarcraft/stargate/portal/PortalOptions.java
+++ b/src/main/java/net/knarcraft/stargate/portal/PortalOptions.java
@@ -5,7 +5,7 @@ import net.knarcraft.stargate.Stargate;
 import java.util.Map;
 
 /**
- * Keeps track of all options for a given portal
+ * Keeps track of all options for one portal
  */
 public class PortalOptions {
 
@@ -37,10 +37,11 @@ public class PortalOptions {
     /**
      * Gets whether this portal is fixed
      *
-     * <p>A fixed portal has only one destination which never changes. A fixed portal has a fixed destination, is a
-     * random portal or is a bungee portal. A fixed portal is always open.</p>
+     * <p>A fixed portal is a portal for which the player cannot choose destination. A portal with a set destination, a
+     * random portal and bungee portals are fixed. While the player has no choice regarding destinations, a fixed gate
+     * may still need to be activated if not set to always on.</p>
      *
-     * @return <p>Whether this gate is fixed</p>
+     * @return <p>Whether this portal is fixed</p>
      */
     public boolean isFixed() {
         return this.isFixed;
@@ -58,6 +59,9 @@ public class PortalOptions {
     /**
      * Gets whether this portal is always on
      *
+     * <p>An always on portal is always open for everyone, and always uses the open-block. It never needs to be
+     * activated or opened manually.</p>
+     *
      * @return <p>Whether this portal is always on</p>
      */
     public boolean isAlwaysOn() {
@@ -67,6 +71,10 @@ public class PortalOptions {
     /**
      * Gets whether this portal is hidden
      *
+     * <p>A hidden portal will be hidden on a network for everyone but admins and the portal owner. In other words,
+     * when selecting a destination using a portal's sign, hidden gates will only be available in the list for the
+     * owner and players with the appropriate permission.</p>
+     *
      * @return <p>Whether this portal is hidden</p>
      */
     public boolean isHidden() {
@@ -76,6 +84,9 @@ public class PortalOptions {
     /**
      * Gets whether this portal is private
      *
+     * <p>A private portal can only be opened by the owner and players with the appropriate permission. A private gate
+     * is not hidden unless the hidden option is also enabled.</p>
+     *
      * @return <p>Whether this portal is private</p>
      */
     public boolean isPrivate() {
@@ -85,6 +96,9 @@ public class PortalOptions {
     /**
      * Gets whether this portal is free
      *
+     * <p>A free portal is exempt from any fees which would normally occur from using the portal. It does nothing if
+     * economy is disabled.</p>
+     *
      * @return <p>Whether this portal is free</p>
      */
     public boolean isFree() {
@@ -94,7 +108,8 @@ public class PortalOptions {
     /**
      * Gets whether this portal is backwards
      *
-     * <p>A backwards portal is one where players exit through the back.</p>
+     * <p>A backwards portal is one where players exit through the back. It's important to note that the exit is
+     * mirrored, not rotated, when exiting backwards.</p>
      *
      * @return <p>Whether this portal is backwards</p>
      */
@@ -105,6 +120,9 @@ public class PortalOptions {
     /**
      * Gets whether this portal is shown on the network even if it's always on
      *
+     * <p>Normally, always-on portals are not selectable on a network, but enabling this option allows the portal to be
+     * shown.</p>
+     *
      * @return <p>Whether portal gate is shown</p>
      */
     public boolean isShown() {
@@ -114,6 +132,10 @@ public class PortalOptions {
     /**
      * Gets whether this portal shows no network
      *
+     * <p>Enabling the no network option allows the portal's network to be hidden for whatever reason. If allowing
+     * normal players to create portals, this can be used to prevent random users from connecting gates to
+     * "protected networks".</p>
+     *
      * @return <p>Whether this portal shows no network/p>
      */
     public boolean isNoNetwork() {
@@ -123,6 +145,8 @@ public class PortalOptions {
     /**
      * Gets whether this portal goes to a random location on the network
      *
+     * <p>A random portal is always on and will teleport to a random destination within the same network.</p>
+     *
      * @return <p>Whether this portal goes to a random location</p>
      */
     public boolean isRandom() {
@@ -132,6 +156,9 @@ public class PortalOptions {
     /**
      * Gets whether this portal is a bungee portal
      *
+     * <p>A bungee portal is able to teleport to a portal on another server. It works differently from other portals as
+     * it does not have a network, but instead the network line specifies the same of the server it connects to.</p>
+     *
      * @return <p>Whether this portal is a bungee portal</p>
      */
     public boolean isBungee() {