Config Comment Cleanup (#1803)

* First pass of the big config cleanup

Mainly focused on bringing comment formatting and rewriting things that
weren't clear. Fixed a few typos here and there and generally tried to
make everything more consistent.

* Some suggestions by Inscrutable

true/false > enabled/disabled
'asynchronously'

* Some more cleanup

Removed config for a feature that was removed mid 2016
a1ac6cc#diff-4e6f4ff49ad98848b830a9c9b425940c

src/main/java/org/spongepowered/common/config/category/AsyncLightingCategory.java

@@ -30,10 +30,10 @@
 @ConfigSerializable
 public class AsyncLightingCategory extends ConfigCategory {
 
-    @Setting(value = "enabled", comment = "If enabled, runs lighting updates async.")
+    @Setting(value = "enabled", comment = "If 'true', lighting updates are run asynchronously.")
     private boolean enabled = true;
 
-    @Setting(value = "num-threads", comment = "The amount of threads to dedicate for async lighting updates. (Default: 2)")
+    @Setting(value = "num-threads", comment = "The amount of threads to dedicate for asynchronous lighting updates. (Default: 2)")
     private int numAsyncThreads = 2;
 
     public boolean isEnabled() {

src/main/java/org/spongepowered/common/config/category/BlockCapturingCategory.java

@@ -33,7 +33,7 @@
 @ConfigSerializable
 public class BlockCapturingCategory extends ConfigCategory {
 
-    @Setting(value = "auto-populate", comment = "If enabled, newly discovered blocks will be added to this config with a default value.")
+    @Setting(value = "auto-populate", comment = "If 'true', newly discovered blocks will be added to this config with a default value.")
     private boolean autoPopulate = false;
 
     @Setting(value = "mods", comment = "Per-mod block id mappings for controlling capturing behavior")

src/main/java/org/spongepowered/common/config/category/BlockCapturingModCategory.java

@@ -33,9 +33,10 @@
 @ConfigSerializable
 public class BlockCapturingModCategory extends ConfigCategory {
 
-    @Setting(value = "enabled", comment = "Set to false if you want to ignore all specific rules for this mod")
+    @Setting(value = "enabled", comment = "If 'false', all specific rules for this mod will be ignored.")
     private boolean isEnabled = true;
-    @Setting(value = "block-tick-capturing", comment = "Set to true to perform individual capturing (i.e. skip bulk capturing) for scheduled ticks for a block type")
+    @Setting(value = "block-tick-capturing", comment = "If 'true', individual capturing (i.e. skip bulk capturing) for scheduled ticks for \n"
+                                                     + "a block type will be performed.")
     private Map<String, Boolean> blockMap = new HashMap<>();
 
     public BlockCapturingModCategory() {

src/main/java/org/spongepowered/common/config/category/BlockTrackingCategory.java

@@ -33,10 +33,11 @@
 @ConfigSerializable
 public class BlockTrackingCategory extends ConfigCategory {
 
-    @Setting(value = "enabled", comment = "If enabled, adds player tracking support for block positions. Note: This should only be disabled if you do not care who caused a block to change.")
+    @Setting(value = "enabled", comment = "If 'true', adds player tracking support for block positions. \n"
+                                        + "Note: This should only be disabled if you do not care who caused a block to change.")
     private boolean enabled = true;
 
-    @Setting(value = "block-blacklist", comment = "Add block ids you wish to blacklist for player block placement tracking.")
+    @Setting(value = "block-blacklist", comment = "Block IDs that will be blacklisted for player block placement tracking.")
     private List<String> blockBlacklist = new ArrayList<>();
 
     public boolean isEnabled() {

src/main/java/org/spongepowered/common/config/category/BungeeCordCategory.java

@@ -30,7 +30,7 @@
 @ConfigSerializable
 public class BungeeCordCategory extends ConfigCategory {
 
-    @Setting(value = "ip-forwarding", comment = "If enabled, allows BungeeCord to forward IP address, UUID, and Game Profile to this server")
+    @Setting(value = "ip-forwarding", comment = "If 'true', allows BungeeCord to forward IP address, UUID, and Game Profile to this server.")
     private boolean ipForwarding = false;
 
     public boolean getIpForwarding() {

src/main/java/org/spongepowered/common/config/category/CollisionModCategory.java

@@ -33,9 +33,9 @@
 @ConfigSerializable
 public class CollisionModCategory extends ConfigCategory {
 
-    @Setting(value = "enabled", comment = "Set to false if you want mod to ignore entity collision rules.")
+    @Setting(value = "enabled", comment = "If 'false', entity collision rules for this mod will be ignored.")
     private boolean isEnabled = true;
-    @Setting(value = "defaults", comment = "Default max collisions used for all entities/blocks unless overridden.")
+    @Setting(value = "defaults", comment = "Default maximum collisions used for all entities/blocks unless overridden.")
     private Map<String, Integer> defaultMaxCollisions = new HashMap<>();
     @Setting(value = "blocks")
     private Map<String, Integer> blockList = new HashMap<>();

src/main/java/org/spongepowered/common/config/category/CommandsCategory.java

@@ -33,12 +33,13 @@
 @ConfigSerializable
 public class CommandsCategory extends ConfigCategory {
 
-    @Setting(comment = "A mapping from unqualified command alias to plugin id of the plugin that should handle a certain command")
+    @Setting(comment = "Command aliases will resolve conflicts when multiple plugins request a specific command, \n"
+                     + "Correct syntax is <unqualified command>=<plugin name> e.g. \"sethome=homeplugin\"")
     private Map<String, String> aliases = new HashMap<>();
 
 
-    @Setting(value = "multi-world-patches", comment = "Patches the specified commands to respect the world of the sender instead of applying the "
-            + "changes on the all worlds.")
+    @Setting(value = "multi-world-patches", comment = "Patches the specified commands to respect the world of the sender instead of applying the \n"
+                                                    + "changes on the all worlds.")
     private Map<String, Boolean> multiWorldCommandPatches = new HashMap<>();
 
     public Map<String, String> getAliases() {

src/main/java/org/spongepowered/common/config/category/CustomDataRegistrationCategory.java

@@ -52,47 +52,47 @@ public class CustomDataRegistrationCategory extends ConfigCategory {
      *
      * This should be populated after {@link SpongeManipulatorRegistry#bake()}.
      */
-    @Setting(value = "registered-data", comment = "An auto generated list, by Sponge, to provide a list of\n"
-                                                  + "registered custom data manipulators by plugins. Since\n"
-                                                  + "the list is generated AFTER the game starts, modifying\n"
-                                                  + "this list will not affect Sponge's system in any way.\n"
-                                                  + "However, it is advisable to view what registered datas\n"
-                                                  + "exist on a server instance, such that when Sponge completes\n"
-                                                  + "startup, it will be verified that all existing registrations\n"
-                                                  + "are accounted for. A warning will be emitted for any existing\n"
-                                                  + "registrations that were not registered, and moved to the\n"
-                                                  + "'failed-data-list'.")
+    @Setting(value = "registered-data", comment = "An auto generated list, by Sponge, to provide a list of \n"
+                                                + "registered custom data manipulators by plugins. Since \n"
+                                                + "the list is generated AFTER the game starts, modifying \n"
+                                                + "this list will not affect Sponge's system in any way. \n"
+                                                + "However, it is advisable to view what registered datas \n"
+                                                + "exist on a server instance, such that when Sponge completes \n"
+                                                + "startup, it will be verified that all existing registrations \n"
+                                                + "are accounted for. A warning will be emitted for any existing \n"
+                                                + "registrations that were not registered, and moved to the \n"
+                                                + "'failed-data-list'.")
     private Set<String> registeredDataIds = new ConcurrentSkipListSet<>();
 
     /**
      * Again, another auto-populated list of FAILED id's. This is never
      * read from file, except after startup, to specify which id's can
      * be "saved".
      */
-    @Setting(value = "failed-data-list", comment = "An auto generated list, by Sponge, to discover and list\n"
-                                                   + "all failed custom data deserializations at runtime due\n"
-                                                   + "to a lack of the registrations being made by a plugin.\n"
-                                                   + "Not to be confused by failed deserialization due to bad data.\n"
-                                                   + "Modifying the list will result in no effect as Sponge auto\n"
-                                                   + "generates this list. This is merely for user configuration.")
+    @Setting(value = "failed-data-list", comment = "An auto generated list, by Sponge, to discover and list \n"
+                                                 + "all failed custom data deserializations at runtime due \n"
+                                                 + "to a lack of the registrations being made by a plugin. \n"
+                                                 + "Not to be confused by failed deserialization due to bad data. \n"
+                                                 + "Modifying the list will result in no effect as Sponge auto \n"
+                                                 + "generates this list. This is merely for user configuration.")
     private Set<String> discoveredFailedDatas = new ConcurrentSkipListSet<>();
 
     /**
      * This is a configurable list of id's that are to be "purged" on
      * discovery.
      */
-    @Setting(value = "data-to-purge", comment = "A configurable list of registration ids that are to be removed\n"
-                                                + "when discovered for deserialization. This can be controlled by\n"
-                                                + "commands in sponge. It is adviseable to refer to the lists made\n"
-                                                + "available through 'failed-data-list', as using any id's from\n"
-                                                + "'registered-data' will result in custom data being deleted at\n"
-                                                + "every load.")
+    @Setting(value = "data-to-purge", comment = "A configurable list of registration ids that are to be removed \n"
+                                              + "when discovered for deserialization. This can be controlled by \n"
+                                              + "commands in sponge. It is adviseable to refer to the lists made \n"
+                                              + "available through 'failed-data-list', as using any id's from \n"
+                                              + "'registered-data' will result in custom data being deleted at \n"
+                                              + "every load.")
     private Set<String> purgeDatas = new ConcurrentSkipListSet<>();
 
-    @Setting(value = "print-on-discovery", comment = "In the cases where there is already previously discovered data\n"
-                                                     + "we don't want to spam the log on each discovery in certain\n"
-                                                     + "contexts. If it is required, we still can emit the log warning\n"
-                                                     + "when necessary.")
+    @Setting(value = "print-on-discovery", comment = "In the cases where there is already previously discovered data \n"
+                                                   + "we don't want to spam the log on each discovery in certain \n"
+                                                   + "contexts. If it is required, we still can emit the log warning \n"
+                                                   + "when necessary.")
     private boolean printFailedDataOnDiscovery = false;
 
 

src/main/java/org/spongepowered/common/config/category/DebugCategory.java

@@ -30,7 +30,7 @@
 @ConfigSerializable
 public class DebugCategory extends ConfigCategory {
 
-    @Setting(value = "thread-contention-monitoring", comment = "Enable Java's thread contention monitoring for thread dumps")
+    @Setting(value = "thread-contention-monitoring", comment = "If 'true', Java's thread contention monitoring for thread dumps is enabled.")
     private boolean enableThreadContentionMonitoring = false;
     @Setting(value = "dump-chunks-on-deadlock", comment = "Dump chunks in the event of a deadlock")
     private boolean dumpChunksOnDeadlock = false;
@@ -39,7 +39,9 @@ public class DebugCategory extends ConfigCategory {
     @Setting(value = "dump-threads-on-warn", comment = "Dump the server thread on deadlock warning")
     private boolean dumpThreadsOnWarn = false;
 
-    @Setting(value = "concurrent-entity-checks", comment = "Detect and prevent certain attempts to use entities concurrently.\nWARNING: May drastically decrease server performance. Only enable this to debug a pre-existing issue")
+    @Setting(value = "concurrent-entity-checks", comment = "Detect and prevent certain attempts to use entities concurrently. \n"
+                                                         + "WARNING: May drastically decrease server performance. Only set this to 'true' "
+                                                         + "to debug a pre-existing issue.")
     private boolean concurrentChecks = false;
 
     public boolean doConcurrentChecks() {

src/main/java/org/spongepowered/common/config/category/EntityActivationModCategory.java

@@ -33,7 +33,7 @@
 @ConfigSerializable
 public class EntityActivationModCategory extends ConfigCategory {
 
-    @Setting(value = "enabled", comment = "Set to false if you want mod to ignore entity activation rules and always tick.")
+    @Setting(value = "enabled", comment = "If 'false', entity activation rules for this mod will be ignored and always tick.")
     private boolean isEnabled = true;
     @Setting(value = "defaults")
     private Map<String, Integer> defaultRanges = new HashMap<>();

src/main/java/org/spongepowered/common/config/category/EntityActivationRangeCategory.java

@@ -33,7 +33,7 @@
 @ConfigSerializable
 public class EntityActivationRangeCategory extends ConfigCategory {
 
-    @Setting(value = "auto-populate", comment = "If enabled, newly discovered entities will be added to this config with a default value.")
+    @Setting(value = "auto-populate", comment = "If 'true', newly discovered entities will be added to this config with a default value.")
     private boolean autoPopulate = false;
     @Setting(value = "defaults", comment = "Default activation ranges used for all entities unless overridden.")
     private Map<String, Integer> defaultRanges = new HashMap<>();

src/main/java/org/spongepowered/common/config/category/EntityCategory.java

@@ -30,12 +30,12 @@
 @ConfigSerializable
 public class EntityCategory extends ConfigCategory {
 
-    @Setting(value = "max-bounding-box-size", comment = "Max size of an entity's bounding box before removing it. Set to 0 to disable")
+    @Setting(value = "max-bounding-box-size", comment = "Maximum size of an entity's bounding box before removing it. Set to 0 to disable")
     private int maxBoundingBoxSize = 1000;
     @Setting(value = "collision-warn-size",
     comment = "Number of colliding entities in one spot before logging a warning. Set to 0 to disable")
     private int maxCollisionSize = 200;
-    @Setting(value = "max-speed", comment = "Square of the max speed of an entity before removing it. Set to 0 to disable")
+    @Setting(value = "max-speed", comment = "Square of the maximum speed of an entity before removing it. Set to 0 to disable")
     private int maxSpeed = 100;
     @Setting(value = "count-warn-size",
             comment = "Number of entities in one dimension before logging a warning. Set to 0 to disable")

src/main/java/org/spongepowered/common/config/category/EntityCollisionCategory.java

@@ -33,11 +33,13 @@
 @ConfigSerializable
 public class EntityCollisionCategory extends ConfigCategory {
 
-    @Setting(value = "auto-populate", comment = "If enabled, newly discovered entities/blocks will be added to this config with a default value.")
+    @Setting(value = "auto-populate", comment = "If 'true', newly discovered entities/blocks will be added to this config with a default value.")
     private boolean autoPopulate = false;
-    @Setting(value = "max-entities-within-aabb", comment = "Max amount of entities any given entity or block can collide with. This improves performance when there are more than 8 entities on top of eachother such as a 1x1 spawn pen. Set to 0 to disable.")
+    @Setting(value = "max-entities-within-aabb", comment = "Maximum amount of entities any given entity or block can collide with. This improves \n"
+                                                         + "performance when there are more than 8 entities on top of each other such as a 1x1 \n"
+                                                         + "spawn pen. Set to 0 to disable.")
     private int maxEntitiesWithinAABB = 8;
-    @Setting(value = "defaults", comment = "Default max collisions used for all entities/blocks unless overridden.")
+    @Setting(value = "defaults", comment = "Default maximum collisions used for all entities/blocks unless overridden.")
     private Map<String, Integer> defaultMaxCollisions = new HashMap<>();
     @Setting(value = "mods", comment = "Per-mod overrides. Refer to the minecraft default mod for example.")
     private Map<String, CollisionModCategory> modList = new HashMap<>();

src/main/java/org/spongepowered/common/config/category/ExploitCategory.java

@@ -30,9 +30,11 @@
 @ConfigSerializable
 public class ExploitCategory extends ConfigCategory {
 
-    @Setting("prevent-creative-itemstack-name-exploit")
+    @Setting(value = "prevent-creative-itemstack-name-exploit", comment = "Prevents an exploit in which the client sends a packet with the \n"
+                                                                        + "itemstack name exceeding the string limit.")
     private boolean preventItemNameOverflow = true;
-    @Setting("prevent-sign-command-exploit")
+    @Setting(value = "prevent-sign-command-exploit", comment = "Prevents an exploit in which the client sends a packet to update a sign containing \n"
+                                                             + "commands from a player without permission.")
     private boolean preventSignExploit = true;
 
     public boolean isPreventItemNameOverflow() {