From 7da0b805a10eca200b22a09011331f8cefb28b24 Mon Sep 17 00:00:00 2001 From: Olof Larsson Date: Tue, 18 Nov 2014 09:49:11 +0100 Subject: [PATCH] Improve source code comments for MFlag and MPerm. --- .../massivecraft/factions/entity/MFlag.java | 31 ++++++++++++----- .../massivecraft/factions/entity/MPerm.java | 34 ++++++++++++++----- 2 files changed, 48 insertions(+), 17 deletions(-) diff --git a/src/main/java/com/massivecraft/factions/entity/MFlag.java b/src/main/java/com/massivecraft/factions/entity/MFlag.java index 70fe2698..768bd25e 100644 --- a/src/main/java/com/massivecraft/factions/entity/MFlag.java +++ b/src/main/java/com/massivecraft/factions/entity/MFlag.java @@ -132,50 +132,63 @@ public class MFlag extends Entity implements Prioritized, Registerable // FIELDS // -------------------------------------------- // - // The sort order priority 1 is high up, 99999 is far down. + // The sort priority. Low values appear first in sorted lists. + // 1 is high up, 99999 is far down. + // Standard Faction flags use "thousand values" like 1000, 2000, 3000 etc to allow adding new flags inbetween. + // So 1000 might sound like a lot but it's actually the priority for the first flag. private int priority = 0; @Override public int getPriority() { return this.priority; } public MFlag setPriority(int priority) { this.priority = priority; this.changed(); return this; } - // Nice name / Display name + // The name of the flag. According to standard it should be fully lowercase just like the flag id. + // In fact the name and the id of all standard flags are the same. + // I just added the name in case anyone feel like renaming their flags for some reason. // Example: "monsters" private String name = "defaultName"; public String getName() { return this.name; } public MFlag setName(String name) { this.name = name; this.changed(); return this; } - // Description + // The flag function described as a question. // Example: "Can monsters spawn in this territory?" private String desc = "defaultDesc"; public String getDesc() { return this.desc; } public MFlag setDesc(String desc) { this.desc = desc; this.changed(); return this; } - // Description Yes + // The flag function described when true. // Example: "Monsters can spawn in this territory." private String descYes = "defaultDescYes"; public String getDescYes() { return this.descYes; } public MFlag setDescYes(String descYes) { this.descYes = descYes; this.changed(); return this; } - // Description No + // The flag function described when false. // Example: "Monsters can NOT spawn in this territory." private String descNo = "defaultDescNo"; public String getDescNo() { return this.descNo; } public MFlag setDescNo(String descNo) { this.descNo = descNo; this.changed(); return this; } - // Standard value + // What is the standard (aka default) flag value? + // This value will be set for factions from the beginning. // Example: false (per default monsters do not spawn in faction territory) private boolean standard = true; public boolean isStandard() { return this.standard; } public MFlag setStandard(boolean standard) { this.standard = standard; this.changed(); return this; } - // If it editable by the faction leader (or for who ever the permission is configured) + // Is this flag editable by players? + // With this we mean standard non administrator players. + // All flags can be changed using /f admin. // Example: true (if players want to turn mob spawning on I guess they should be able to) private boolean editable = false; public boolean isEditable() { return this.editable; } public MFlag setEditable(boolean editable) { this.editable = editable; this.changed(); return this; } - // If the flag is visible or hidden. + // Is this flag visible to players? + // With this we mean standard non administrator players. + // All flags can be seen using /f admin. + // Some flags can be rendered meaningless by settings in Factions or external plugins. + // Say we set "editable" to false and "standard" to true for the "open" flag to force all factions being open. + // In such case we might want to hide the open flag by setting "visible" false. + // If it can't be changed, why bother showing it? // Example: true (yeah we need to see this flag) - // Explanation: Some flags are rendered meaningless by other plugins. Say we have a creative mode server without any mobs. The server owner might want to hide this flag. private boolean visible = true; public boolean isVisible() { return this.visible; } public MFlag setVisible(boolean visible) { this.visible = visible; this.changed(); return this; } diff --git a/src/main/java/com/massivecraft/factions/entity/MPerm.java b/src/main/java/com/massivecraft/factions/entity/MPerm.java index 6b339d26..c9e61f59 100644 --- a/src/main/java/com/massivecraft/factions/entity/MPerm.java +++ b/src/main/java/com/massivecraft/factions/entity/MPerm.java @@ -188,43 +188,61 @@ public class MPerm extends Entity implements Prioritized, Registerable // FIELDS // -------------------------------------------- // - // The sort order priority 1 is high up, 99999 is far down. + // The sort priority. Low values appear first in sorted lists. + // 1 is high up, 99999 is far down. + // Standard Faction perms use "thousand values" like 1000, 2000, 3000 etc to allow adding new perms inbetween. + // So 1000 might sound like a lot but it's actually the priority for the first perm. private int priority = 0; @Override public int getPriority() { return this.priority; } public MPerm setPriority(int priority) { this.priority = priority; this.changed(); return this; } - // Nice name / Display name + // The name of the perm. According to standard it should be fully lowercase just like the perm id. + // In fact the name and the id of all standard perms are the same. + // I just added the name in case anyone feel like renaming their perms for some reason. // Example: "build" private String name = "defaultName"; public String getName() { return this.name; } public MPerm setName(String name) { this.name = name; this.changed(); return this; } - // Short description + // The perm function described as an "order". + // The desc should match the format: + // "You are not allowed to X." + // "You are not allowed to edit the terrain." // Example: "edit the terrain" private String desc = "defaultDesc"; public String getDesc() { return this.desc; } public MPerm setDesc(String desc) { this.desc = desc; this.changed(); return this; } - // Standard value + // What is the standard (aka default) perm value? + // This value will be set for factions from the beginning. // Example: ... set of relations ... private Set standard = new LinkedHashSet(); public Set getStandard() { return this.standard; } public MPerm setStandard(Set standard) { this.standard = standard; this.changed(); return this; } - // Is this a territory permission? + // Is this a territory perm meaning it has to do with territory construction, modification or interaction? + // True Examples: build, container, door, lever etc. + // False Examples: name, invite, home, sethome, deposit, withdraw etc. private boolean territory = false; public boolean isTerritory() { return this.territory; } public MPerm setTerritory(boolean territory) { this.territory = territory; this.changed(); return this; } - // If it editable by the faction leader (or for who ever the permission is configured) + // Is this perm editable by players? + // With this we mean standard non administrator players. + // All perms can be changed using /f admin. // Example: true (all perms are editable by default) private boolean editable = false; public boolean isEditable() { return this.editable; } public MPerm setEditable(boolean editable) { this.editable = editable; this.changed(); return this; } - // If the flag is visible or hidden. + // Is this perm visible to players? + // With this we mean standard non administrator players. + // All perms can be seen using /f admin. + // Some perms can be rendered meaningless by settings in Factions or external plugins. + // Say we set "editable" to false. + // In such case we might want to hide the perm by setting "visible" false. + // If it can't be changed, why bother showing it? // Example: true (yeah we need to see this permission) - // Explanation: Some flags are rendered meaningless by other plugins. private boolean visible = true; public boolean isVisible() { return this.visible; } public MPerm setVisible(boolean visible) { this.visible = visible; this.changed(); return this; }