From 284021c523c7b89bb9c5ce1890cc91c3cdd9e903 Mon Sep 17 00:00:00 2001
From: Michael <Michael@some.where>
Date: Sun, 16 Apr 2017 08:34:02 -0400
Subject: [PATCH] Document terminal command system

---
 ShiftOS_TheReturn/Command.cs | 100 +++++++++++++++++++++++++++++++++--
 1 file changed, 96 insertions(+), 4 deletions(-)

diff --git a/ShiftOS_TheReturn/Command.cs b/ShiftOS_TheReturn/Command.cs
index a5924ed..c6d58e1 100644
--- a/ShiftOS_TheReturn/Command.cs
+++ b/ShiftOS_TheReturn/Command.cs
@@ -30,23 +30,53 @@ using System.Threading.Tasks;
 
 namespace ShiftOS.Engine
 {
+    /// <summary>
+    /// Denotes that the following terminal command or namespace must only be used in an elevated environment.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = false)]
     public class KernelModeAttribute : Attribute
     {
 
     }
 
+    /// <summary>
+    /// Denotes that the following public static method is a ShiftOS Terminal command.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
     public class Command : Attribute
     {
+        /// <summary>
+        /// The command name.
+        /// </summary>
         public string name;
+        /// <summary>
+        /// The description of the command.
+        /// </summary>
         public string description = "";
+        /// <summary>
+        /// The usage flags for the command.
+        /// </summary>
         public string usage = "";
+        /// <summary>
+        /// Should the command be hidden from the help system?
+        /// </summary>
         public bool hide = false;
 
+        /// <summary>
+        /// Creates a new instance of the <see cref="Command"/>. 
+        /// </summary>
+        /// <param name="name">The name of the command.</param>
         public Command(string name)
         {
             this.name = name;
         }
+
+
+        /// <summary>
+        /// Creates a new instance of the <see cref="Command"/>. 
+        /// </summary>
+        /// <param name="name">The name of the command.</param>
+        /// <param name="hide">Whether the command should be hidden from the help system.</param>
         public Command(string name, bool hide)
         {
             this.name = name;
@@ -60,9 +90,20 @@ namespace ShiftOS.Engine
         }
     }
 
+    /// <summary>
+    /// Denotes that this function or property is dependent on a Shiftorium upgrade.
+    /// </summary>
+   [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method | AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false)]
     public class RequiresUpgradeAttribute : Attribute
     {
+        /// <summary>
+        /// Gets or sets the upgrade(s) this attribute requires.
+        /// </summary>
         public string Upgrade { get; set; }
+
+        /// <summary>
+        /// Gets whether the dependent upgrade(s) are installed.
+        /// </summary>
         public bool Installed
         {
             get
@@ -94,14 +135,35 @@ namespace ShiftOS.Engine
         }
     }
 
+    /// <summary>
+    /// Denotes a Terminal command namespace.
+    /// </summary>
     public class Namespace : Attribute
     {
+        /// <summary>
+        /// The namespace's name.
+        /// </summary>
         public string name;
+        /// <summary>
+        /// Whether the namespace should be hidden from the help system. Overrides all child <see cref="Command"/>s' hide values. 
+        /// </summary>
         public bool hide;
+
+        /// <summary>
+        /// Creates a new instance of the <see cref="Namespace"/>. 
+        /// </summary>
+        /// <param name="n">The name of the namespace.</param>
         public Namespace(string n)
         {
             name = n;
         }
+
+
+        /// <summary>
+        /// Creates a new instance of the <see cref="Namespace"/>. 
+        /// </summary>
+        /// <param name="n">The name of the namespace.</param>
+        /// <param name="hide">Whether this namespace should be hidden from the user.</param>
         public Namespace(string n, bool hide)
         {
             name = n;
@@ -109,13 +171,34 @@ namespace ShiftOS.Engine
         }
     }
 
+    /// <summary>
+    /// Marks a Terminal command as obsolete.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Method)]
     public class CommandObsolete : Attribute
     {
+        /// <summary>
+        /// The reason of obsolescence.
+        /// </summary>
         public string reason;
+
+        /// <summary>
+        /// If a new command has the same functionality, this is it.
+        /// </summary>
         public string newcommand;
+
+        /// <summary>
+        /// Should we warn the user when they run this command?
+        /// </summary>
         public bool warn;
 
+
+        /// <summary>
+        /// Creates a new instance of the <see cref="CommandObsolete"/> class. 
+        /// </summary>
+        /// <param name="reason">The reason for this command's obsolescence. You can use "%n" in place of the new command name.</param>
+        /// <param name="newcommand">If a new command is set to take over, specify it here.</param>
+        /// <param name="warn">Whether or not we should warn the user when they run the command.</param>
         public CommandObsolete(string reason, string newcommand, bool warn)
         {
             this.reason = reason; // %n for newcommand
@@ -124,11 +207,21 @@ namespace ShiftOS.Engine
         }
     }
 
+    /// <summary>
+    /// Denotes that this command requires a specified argument to be in its argument dictionary.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
     public class RequiresArgument : Attribute
     {
+        /// <summary>
+        /// The argument name
+        /// </summary>
         public string argument;
 
+        /// <summary>
+        /// Creates a new instance of the <see cref="RequiresArgument"/> attribute 
+        /// </summary>
+        /// <param name="argument">The argument name associated with this attribute</param>
         public RequiresArgument(string argument)
         {
             this.argument = argument;
@@ -143,12 +236,11 @@ namespace ShiftOS.Engine
         }
     }
 
+    /// <summary>
+    /// Prevents a command from being run in a remote session.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
     public class RemoteLockAttribute : Attribute
     {
-        /// <summary>
-        /// When used on a terminal command, it will prevent that command from being invoked by a remote user (over MUD terminal forwarding).
-        /// </summary>
-        public RemoteLockAttribute() { }
     }
 }