Improve DrawOp documentation and prefer explicit GetBlockIfAllowed in…

…stead

MCGalaxy/Commands/CommandParser.cs

@@ -202,6 +202,7 @@ public static class CommandParser {
 
         /// <summary> Attempts to parse the given argument as either a block name or a block ID. </summary>
         /// <remarks> Also ensures the player is allowed to place the given block. </remarks>
+        [Obsolete("Use GetBlockIfAllowed with explicit action argument instead")]
         public static bool GetBlockIfAllowed(Player p, string input, out BlockID block, bool allowSkip = false) {
             return GetBlockIfAllowed(p, input, "draw with", out block, allowSkip);
         }

MCGalaxy/Commands/Moderation/CmdPass.cs

@@ -103,7 +103,7 @@ public sealed class CmdPass : Command2 {
         }
 
         bool CheckResetPerms(Player p, CommandData data) {
-            // check server owner name for backwards compatibility
+            // check server owner name for permissions backwards compatibility
             return Server.Config.OwnerName.CaselessEq(p.name) || CheckExtraPerm(p, data, 1);
         }
 

MCGalaxy/Commands/building/CmdOutline.cs

@@ -26,13 +26,14 @@ public sealed class CmdOutline : DrawCmd {
         public override LevelPermission defaultRank { get { return LevelPermission.AdvBuilder; } }
 
         protected override DrawOp GetDrawOp(DrawArgs dArgs) {
+            Player p = dArgs.Player;
             if (dArgs.Message.Length == 0) {
-                dArgs.Player.Message("Block name is required."); return null;
+                p.Message("Block name is required."); return null;
             }
 
             BlockID target;
             string[] parts = dArgs.Message.SplitSpaces(2);
-            if (!CommandParser.GetBlockIfAllowed(dArgs.Player, parts[0], out target)) return null;
+            if (!CommandParser.GetBlockIfAllowed(p, parts[0], "draw with", out target)) return null;
 
             OutlineDrawOp op = new OutlineDrawOp();
             // e.g. testing air 'above' grass - therefore op.Above needs to be false for 'up mode'

MCGalaxy/Commands/building/CmdReplaceBrush.cs

@@ -40,7 +40,7 @@ public class CmdReplaceBrush : DrawCmd {
 
 
             BlockID target;
-            if (!CommandParser.GetBlockIfAllowed(p, args[0], out target)) return null;
+            if (!CommandParser.GetBlockIfAllowed(p, args[0], "draw with", out target)) return null;
 
             BrushFactory factory = BrushFactory.Find(args[1]);
             if (factory == null) {

MCGalaxy/Database/BlockDB/BlockDBEntry.cs

@@ -80,11 +80,11 @@ public static class BlockDBFlags {
         public const ushort Restored    = 1 << 7;
         public const ushort UndoOther   = 1 << 8;
         public const ushort UndoSelf    = 1 << 9;
-        public const ushort RedoSelf    = 1 << 10;        
+        public const ushort RedoSelf    = 1 << 10;
         public const ushort FixGrass    = 1 << 11;
 
         public const ushort OldExtended2 = 1 << 12;
-        public const ushort NewExtended2 = 1 << 13;        
+        public const ushort NewExtended2 = 1 << 13;
         public const ushort OldExtended  = 1 << 14;
         public const ushort NewExtended  = 1 << 15;
     }

MCGalaxy/Drawing/BrushFactories/FrequencyBrushes.cs

@@ -46,7 +46,7 @@ public static class FrequencyBrush
 
                 int sepIndex = parts[i].IndexOf('/'); 
                 string arg = sepIndex >= 0 ? parts[i].Substring(0, sepIndex) : parts[i];
-                if (!CommandParser.GetBlockIfAllowed(p, arg, out blocks[j], true)) return null;
+                if (!CommandParser.GetBlockIfAllowed(p, arg, "draw with", out blocks[j], true)) return null;
 
                 if (sepIndex >= 0) {
                     arg = parts[i].Substring(sepIndex + 1);

MCGalaxy/Drawing/BrushFactories/ReplaceBrushes.cs

@@ -56,23 +56,25 @@ public sealed class ReplaceBrushFactory : BrushFactory
             for (int i = 0; i < blocks.Length; i++)
                 blocks[i] = Block.Invalid;
 
-            for (int i = 0; start < max; start++, i++ ) {
+            for (int i = 0; start < max; start++, i++) 
+            {
                 BlockID block;
-                if (!CommandParser.GetBlockIfAllowed(p, parts[start], out block)) return null;
-
+                if (!CommandParser.GetBlockIfAllowed(p, parts[start], "draw with", out block)) return null;
                 blocks[i] = block;
             }
             return blocks;
         }
 
         static bool GetTargetBlock(BrushArgs args, string[] parts, out BlockID target) {
+            Player p = args.Player;
             target = 0;
+
             if (parts.Length == 1) {
-                if (!CommandParser.IsBlockAllowed(args.Player, "draw with", args.Block)) return false;
+                if (!CommandParser.IsBlockAllowed(p, "draw with", args.Block)) return false;
 
                 target = args.Block; return true;
             }            
-            return CommandParser.GetBlockIfAllowed(args.Player, parts[parts.Length - 1], out target);
+            return CommandParser.GetBlockIfAllowed(p, parts[parts.Length - 1], "draw with", out target);
         }
     }
 

MCGalaxy/Drawing/BrushFactories/SimpleBrushes.cs

@@ -33,20 +33,21 @@ public sealed class SolidBrushFactory : BrushFactory
         };
 
         public override Brush Construct(BrushArgs args) {
+            Player p = args.Player;
             if (args.Message.Length == 0) {
-                if (!CommandParser.IsBlockAllowed(args.Player, "draw with", args.Block)) return null;
+                if (!CommandParser.IsBlockAllowed(p, "draw with", args.Block)) return null;
                 return new SolidBrush(args.Block);
             }
 
             BlockID block;
-            if (!CommandParser.GetBlockIfAllowed(args.Player, args.Message, out block)) return null;
+            if (!CommandParser.GetBlockIfAllowed(p, args.Message, "draw with", out block)) return null;
             return new SolidBrush(block);
         }
 
         public override bool Validate(BrushArgs args) {
             if (args.Message.Length == 0) return true;
             BlockID block;
-            return CommandParser.GetBlockIfAllowed(args.Player, args.Message, out block);
+            return CommandParser.GetBlockIfAllowed(args.Player, args.Message, "draw with", out block);
         }
     }
 
@@ -63,26 +64,27 @@ public sealed class CheckeredBrushFactory : BrushFactory
         };
 
         public override Brush Construct(BrushArgs args) {
+            Player p = args.Player;
             if (args.Message.Length == 0) {
-                if (!CommandParser.IsBlockAllowed(args.Player, "draw with", args.Block)) return null;
+                if (!CommandParser.IsBlockAllowed(p, "draw with", args.Block)) return null;
                 return new CheckeredBrush(args.Block, Block.Invalid);
             }
             string[] parts = args.Message.SplitSpaces();
 
             BlockID block1;
-            if (!CommandParser.GetBlockIfAllowed(args.Player, parts[0], out block1, true)) return null;
+            if (!CommandParser.GetBlockIfAllowed(p, parts[0], "draw with", out block1, true)) return null;
             if (parts.Length == 1)
                 return new CheckeredBrush(block1, Block.Invalid);
 
             if (parts.Length == 2) {
                 BlockID block2;
-                if (!CommandParser.GetBlockIfAllowed(args.Player, parts[1], out block2, true)) return null;
+                if (!CommandParser.GetBlockIfAllowed(p, parts[1], "draw with", out block2, true)) return null;
                 return new CheckeredBrush(block1, block2);
             }
 
             BlockID[] blocks = new BlockID[parts.Length];
             for (int i = 0; i < blocks.Length; i++) {
-                if (!CommandParser.GetBlockIfAllowed(args.Player, parts[i], out blocks[i], true)) return null;
+                if (!CommandParser.GetBlockIfAllowed(p, parts[i], "draw with", out blocks[i], true)) return null;
             }            
             return new CheckeredPaletteBrush(blocks);
         }
@@ -138,19 +140,20 @@ public sealed class StripedBrushFactory : BrushFactory
         };
 
         public override Brush Construct(BrushArgs args) {
+            Player p = args.Player;
             if (args.Message.Length == 0) {
-                if (!CommandParser.IsBlockAllowed(args.Player, "draw with", args.Block)) return null;
+                if (!CommandParser.IsBlockAllowed(p, "draw with", args.Block)) return null;
                 return new StripedBrush(args.Block, Block.Air);
             }
             string[] parts = args.Message.SplitSpaces();
 
             BlockID block1;
-            if (!CommandParser.GetBlockIfAllowed(args.Player, parts[0], out block1, true)) return null;
+            if (!CommandParser.GetBlockIfAllowed(p, parts[0], "draw with", out block1, true)) return null;
             if (parts.Length == 1)
                 return new StripedBrush(block1, Block.Air);
 
             BlockID block2;
-            if (!CommandParser.GetBlockIfAllowed(args.Player, parts[1], out block2, true)) return null;
+            if (!CommandParser.GetBlockIfAllowed(p, parts[1], "draw with", out block2, true)) return null;
             return new StripedBrush(block1, block2);
         }
     }

MCGalaxy/Drawing/DrawOps/DrawOp.cs

@@ -40,26 +40,26 @@ public abstract class DrawOp
         //public long TotalAffected; // blocks affected by the draw operation
         public long TotalModified; // blocks actually modified (e.g. some may not be due to permissions)
 
-        /// <summary> Minimum coordinates of the bounds of this drawing command. </summary>
+        /// <summary> Minimum coordinates of the bounds of this draw operation </summary>
         public Vec3S32 Min;
 
-        /// <summary> Maximum coordinates of the bounds of this drawing command. </summary>
+        /// <summary> Maximum coordinates of the bounds of this draw operation </summary>
         public Vec3S32 Max;
 
-        /// <summary> Coordinates of the first point selected by the user. </summary>
+        /// <summary> Coordinates of the first point selected by the player </summary>
         public Vec3S32 Origin;
 
-        /// <summary> Coordinates of the current block being processed by the drawing command. </summary>
+        /// <summary> Coordinates of the current block being processed by this draw operation </summary>
         /// <remarks> Note: You should treat this as coordinates, it is a DrawOpBlock struct for performance reasons. </remarks>
         public DrawOpBlock Coords;
 
-        /// <summary> Player that is executing the draw operation. </summary>
+        /// <summary> Player that is executing this draw operation </summary>
         public Player Player;
 
-        /// <summary> Level the draw operation is being performed upon. </summary>
+        /// <summary> Level that this draw operation is being performed on </summary>
         public Level Level;
 
-        /// <summary> BlockDB change flags for blocks affected by this draw operation. </summary>
+        /// <summary> BlockDB change flags for blocks affected by this draw operation </summary>
         public ushort Flags = BlockDBFlags.Drawn;
 
         /// <summary> Lock held on the associated level's BlockDB. Can be null. </summary>
@@ -78,8 +78,8 @@ public abstract class DrawOp
         /// <summary> Whether the output of this draw operation is affected by the player's current Transform. </summary>
         public bool AffectedByTransform = true;
 
-        /// <summary> Estimates the total number of blocks that the drawing commands affects. <br/>
-        /// Note that this estimate assumes that all possibly affected blocks will be changed by the drawing command. </summary>
+        /// <summary> Estimates the total number of blocks that this draw operation may affect. </summary>
+        /// <remarks> This estimate assumes that all potentially affected blocks will be changed by the draw operation </remarks>
         public abstract long BlocksAffected(Level lvl, Vec3S32[] marks);
 
         public abstract void Perform(Vec3S32[] marks, Brush brush, DrawOpOutput output);