Merge pull request #2816 from ScottNZ/radoc

radoc tidy

OpenRA.FileFormats/FieldLoader.cs

@@ -355,7 +355,7 @@ namespace OpenRA.FileFormats
 	// mirrors DescriptionAttribute from System.ComponentModel but we dont want to have to use that everywhere.
 	public class DescAttribute : Attribute
 	{
-		public readonly string Description;
+		public readonly string[] Lines;
-		public DescAttribute(string description) { Description = description; }
+		public DescAttribute(params string[] lines) { Lines = lines; }
 	}
 }

OpenRA.Game/GameRules/ActorInfo.cs

@@ -17,14 +17,14 @@ using OpenRA.Traits;
 namespace OpenRA
 {
 	//TODO: This is not exported into the documentation yet.
-	[Desc("A unit/building inside the game. Every rules starts with one and adds trait to it.\n" +
+	[Desc("A unit/building inside the game. Every rules starts with one and adds trait to it.",
-	      "\t# Special actors like world or player are usually defined in system.yaml and effect everything.")]
+		"Special actors like world or player are usually defined in system.yaml and affect everything.")]
 	public class ActorInfo
 	{
-		[Desc("The actor name can be anything, but the sprites used in the Render*: traits default to this one.\n" +
+		[Desc("The actor name can be anything, but the sprites used in the Render*: traits default to this one.",
-		      "\t# Also if you add an ^ in front of the name, the engine will recognize this as a collection of traits\n" +
+			"If you add an ^ in front of the name, the engine will recognize this as a collection of traits",
-		      "\t# that can be inherited by others (using Inherits:) and not a real unit." +
+			"that can be inherited by others (using Inherits:) and not a real unit.",
-		      "\t# You can remove inherited traits by adding a - infront of them as in -TraitName: to inherit everything, but this trait.")]
+			"You can remove inherited traits by adding a - infront of them as in -TraitName: to inherit everything, but this trait.")]
 		public readonly string Name;
 		public readonly TypeDictionary Traits = new TypeDictionary();
 

OpenRA.Mods.RA/Attack/AttackMedic.cs

@@ -14,9 +14,9 @@ using OpenRA.FileFormats;
 
 namespace OpenRA.Mods.RA
 {
-	[Desc("Give the unit a \"heal-weapon\".\n" +
+	[Desc("Give the unit a \"heal-weapon\".",
-	      "\t# It conflicts with any other weapon or Attack*: trait because it will hurt friendlies during the\n" +
+		"It conflicts with any other weapon or Attack*: trait because it will hurt friendlies during the",
-	      "\t# heal process then. It also won't work with buildings (use RepairsUnits: for them).")]
+		"heal process then. It also won't work with buildings (use RepairsUnits: for them)")]
 	public class AttackMedicInfo : AttackFrontalInfo
 	{
 		public override object Create( ActorInitializer init ) { return new AttackMedic( init.self, this ); }

OpenRA.Mods.RA/Capturable.cs

@@ -23,8 +23,7 @@ namespace OpenRA.Mods.RA
 		public readonly bool AllowAllies = false;
 		public readonly bool AllowNeutral = true;
 		public readonly bool AllowEnemies = true;
-		[Desc("Seconds it takes to change the owner.\n" +
+		[Desc("Seconds it takes to change the owner.", "It stays neutral during this period. You might want to add a CapturableBar: trait, too.")]
-		      "\t# It stays neutral during this period. You might want to add a CapturableBar: trait, too.")]
 		public readonly int CaptureCompleteTime = 10;
 
 		public object Create(ActorInitializer init) { return new Capturable(this); }

OpenRA.Mods.RA/FreeActor.cs

@@ -13,15 +13,14 @@ using OpenRA.Traits;
 
 namespace OpenRA.Mods.RA
 {
-	[Desc("Player recives a unit for free once the building is placed. This also works for structures.\n" +
+	[Desc("Player recives a unit for free once the building is placed. This also works for structures.",
-	      "\t # If you want more then one unit to appear copy this section and assign IDs like FreeActor@2, ...")]
+		"If you want more than one unit to appear copy this section and assign IDs like FreeActor@2, ...")]
 	public class FreeActorInfo : ITraitInfo
 	{
 		[ActorReference]
-		[Desc("Name of actor (HARV for refineries)")]
+		[Desc("Name of actor (use HARV if this trait is for refineries)")]
 		public readonly string Actor = null;
-		[Desc("What the unit should start doing. Warning: If this is no harvester\n" +
+		[Desc("What the unit should start doing. Warning: If this is not a harvester", "it will break if you use FindResources.")]
-		      "\t # it will break, when you add FindResources here.")]
 		public readonly string InitialActivity = null;
 		[Desc("Offset relative to structure-center in 2D (e.g. 1, 2)")]
 		public readonly int2 SpawnOffset = int2.Zero;

OpenRA.Mods.RA/GivesExperience.cs

@@ -15,7 +15,7 @@ namespace OpenRA.Mods.RA
 {
 	class GivesExperienceInfo : TraitInfo<GivesExperience>
 	{
-		[Desc("if -1, use the value of the unit cost.")]
+		[Desc("If -1, use the value of the unit cost.")]
 		public readonly int Experience = -1;
 	}
 

OpenRA.Mods.RA/Player/ClassicProductionQueue.cs

@@ -17,20 +17,18 @@ using OpenRA.FileFormats;
 
 namespace OpenRA.Mods.RA
 {
-	[Desc("Attach this to the world actor (not a building!) to define a new shared build queue.\n" +
+	[Desc("Attach this to the world actor (not a building!) to define a new shared build queue.",
-	      "\t# Will only work together with the Production: trait on the actor that actually does the production.\n" +
+		"Will only work together with the Production: trait on the actor that actually does the production.", 
-	      "\t# You will also want to add PrimaryBuildings: to let the user choose where new units should exit.")]
+		"You will also want to add PrimaryBuildings: to let the user choose where new units should exit.")]
 	public class ClassicProductionQueueInfo : ProductionQueueInfo, Requires<TechTreeInfo>, Requires<PowerManagerInfo>, Requires<PlayerResourcesInfo>
 	{
-		[Desc("If you build more actors of the same type, \n" +
+		[Desc("If you build more actors of the same type,", "the same queue will get its build time lowered for every actor produced there.")]
-		      "\t# the same queue will get it's build time lowered for every actor produced there.")]
 		public readonly bool SpeedUp = false;
-		[Desc("Everytime another production building of the same queue is\n" +
+		[Desc("Every time another production building of the same queue is", 
-		      "\t# contructed, the build time of all actors in the queue\n" +
+			"contructed, the build times of all actors in the queue", 
-		      "\t#get divided by this value.")]
+			"are divided by this value.")]
 		public readonly int BuildTimeSpeedUpDivisor = 2;
-		[Desc("You can still build more production buildings\n" +
+		[Desc("You can still build more production buildings", "than this value, but the build time won't increase further.")]
-		      "\t# than this value, but the build time won't increase further.")]
 		public readonly int MaxBuildTimeReductionSteps = 6;
 
 		public override object Create(ActorInitializer init) { return new ClassicProductionQueue(init.self, this); }

OpenRA.Mods.RA/Player/ProductionQueue.cs

@@ -17,9 +17,9 @@ using OpenRA.FileFormats;
 
 namespace OpenRA.Mods.RA
 {
-	[Desc("Attach this to an actor (usually a building) to let it produce units or construct buildings.\n" +
+	[Desc("Attach this to an actor (usually a building) to let it produce units or construct buildings.", 
-	      "\t# If one builds another actor of this type, he will get a separate queue to create two actors\n" +
+		"If one builds another actor of this type, he will get a separate queue to create two actors", 
-	      "\t# at the same time. Will only work together with the Production: trait.")]
+		"at the same time. Will only work together with the Production: trait.")]
 	public class ProductionQueueInfo : ITraitInfo
 	{
 		[Desc("What kind of production will be added (e.g. Building, Infantry, Vehicle, ...)")]
@@ -32,22 +32,21 @@ namespace OpenRA.Mods.RA
 		[Desc("The build time is multiplied with this value on low power.")]
 		public readonly int LowPowerSlowdown = 3;
 
-		[Desc("Notification played when production is complete.\n" +
+		[Desc("Notification played when production is complete.", 
-		      "\t# The filename of the audio is defined per faction in notifications.yaml.")]
+			"The filename of the audio is defined per faction in notifications.yaml.")]
 		public readonly string ReadyAudio = "UnitReady";
-		[Desc("Notification played when you can't train another unit\n" +
+		[Desc("Notification played when you can't train another unit",
-		      "\t# when the build limit exceeded or the exit is jammed.\n" +
+			"when the build limit exceeded or the exit is jammed.",
-		      "\t# The filename of the audio is defined per faction in notifications.yaml.")]
+			"The filename of the audio is defined per faction in notifications.yaml.")]
 		public readonly string BlockedAudio = "NoBuild";
-		[Desc("Notification played when user clicks on the build palette icon.\n" +
+		[Desc("Notification played when user clicks on the build palette icon.",
-		      "\t# The filename of the audio is defined per faction in notifications.yaml.")]
+			"The filename of the audio is defined per faction in notifications.yaml.")]
 		public readonly string QueuedAudio = "Training";
-		[Desc("Notification played when player right-clicks\n" +
+		[Desc("Notification played when player right-clicks on the build palette icon.",
-		      "\t# on the build palette icon. The filename of the audio is defined per faction in notifications.yaml.")]
+			"The filename of the audio is defined per faction in notifications.yaml.")]
 		public readonly string OnHoldAudio = "OnHold";
-		[Desc("Notification played when player right-clicks\n" +
+		[Desc("Notification played when player right-clicks on a build palette icon that is already on hold.",
-		      "\t# on a build palette icon that is already on hold.\n" +
+			"The filename of the audio is defined per faction in notifications.yaml.")]
-		      "\t# The filename of the audio is defined per faction in notifications.yaml.")]
 		public readonly string CancelledAudio = "Cancelled";
 
 		public virtual object Create(ActorInitializer init) { return new ProductionQueue(init.self, init.self.Owner.PlayerActor, this); }

OpenRA.Utility/Command.cs

@@ -477,10 +477,10 @@ namespace OpenRA.Utility
 					destFrames.Select(f => f.Image));
 		}
 
-		static string NiceTypeName(Type t)
+		static string FriendlyTypeName(Type t)
 		{
 			if (t.IsGenericType && t.GetGenericTypeDefinition() == typeof(Dictionary<,>))
-				return "Dictionary<{0},{1}>".F(t.GetGenericArguments().Select(a => NiceTypeName(a)).ToArray ());
+				return "Dictionary<{0},{1}>".F(t.GetGenericArguments().Select(FriendlyTypeName).ToArray());
 
 			return t.Name;
 		}
@@ -492,34 +492,42 @@ namespace OpenRA.Utility
 			Rules.LoadRules(Game.modData.Manifest, new Map());
 
 			Console.WriteLine("## Documentation");
-			Console.WriteLine("This documentation is aimed at modders and contributers of OpenRA. It displays all traits with default values and developer commentary. Please do not edit it directly, but add new `[Desc(\"String\")]` tags to the source code. This file has been automatically generated on {0}. Type `make docs` to create a new one and put it on https://github.com/OpenRA/OpenRA/wiki/Traits afterwards. A copy of this is compiled to HTML and shipped with every release during the automated packaging process.\n", DateTime.Now);
+			Console.WriteLine(
-			Console.WriteLine("```yaml\n\n");
+				"This documentation is aimed at modders and contributers of OpenRA. It displays all traits with default values and developer commentary. " +
+				"Please do not edit it directly, but add new `[Desc(\"String\")]` tags to the source code. This file has been automatically generated on {0}. " +
+				"Type `make docs` to create a new one and put it on https://github.com/OpenRA/OpenRA/wiki/Traits afterwards. " +
+				"A copy of this is compiled to HTML and shipped with every release during the automated packaging process.", DateTime.Now);
+			Console.WriteLine("```yaml");
+			Console.WriteLine();
 
-			foreach(var t in Game.modData.ObjectCreator.GetTypesImplementing<ITraitInfo>())
+			foreach (var t in Game.modData.ObjectCreator.GetTypesImplementing<ITraitInfo>())
 			{
 				if (t.ContainsGenericParameters || t.IsAbstract)
-					continue;		// skip helpers like TraitInfo<T>
+					continue; // skip helpers like TraitInfo<T>
 
-				var traitName = t.Name.Replace("Info","");
+				var traitName = t.Name.EndsWith("Info") ? t.Name.Substring(0, t.Name.Length - 4) : t.Name;
-				var traitDesc = t.GetCustomAttributes<DescAttribute>(false).Select(a => a.Description).FirstOrDefault();
+				var traitDescLines = t.GetCustomAttributes<DescAttribute>(false).SelectMany(d => d.Lines);
-				if (!string.IsNullOrEmpty(traitDesc))
+				Console.WriteLine("{0}:{1}", traitName, traitDescLines.Count() == 1 ? " # " + traitDescLines.First() : "");
-					traitDesc = " # {0}".F(traitDesc);
+				if (traitDescLines.Count() >= 2)
+					foreach (var line in traitDescLines)
+						Console.WriteLine("\t# {0}", line);
 
-				Console.WriteLine("\t{0}:{1}", traitName, traitDesc);
 				var liveTraitInfo = Game.modData.ObjectCreator.CreateBasic(t);
 
-				foreach(var f in t.GetFields(BindingFlags.Public | BindingFlags.Instance | BindingFlags.FlattenHierarchy))
+				foreach (var f in t.GetFields(BindingFlags.Public | BindingFlags.Instance | BindingFlags.FlattenHierarchy))
 				{
-					var fieldDesc = f.GetCustomAttributes<DescAttribute>(true).Select(a => a.Description).FirstOrDefault();
+					var fieldDescLines = f.GetCustomAttributes<DescAttribute>(true).SelectMany(d => d.Lines);
-					if (!string.IsNullOrEmpty(fieldDesc))
+					var fieldType = FriendlyTypeName(f.FieldType);
-						fieldDesc = ", {0}".F(fieldDesc);
-					var fieldType = NiceTypeName(f.FieldType);
 					var defaultValue = FieldSaver.SaveField(liveTraitInfo, f.Name).Value.Value;
-
+					Console.WriteLine("\t{0}: {1} # Type: {2}{3}", f.Name, defaultValue, fieldType, fieldDescLines.Count() == 1 ? ". " + fieldDescLines.First() : "");
-					Console.WriteLine("\t\t{0}: {2}  # Type: {1}{3}", f.Name, fieldType, defaultValue, fieldDesc);
+					if (fieldDescLines.Count() >= 2)
+						foreach (var line in fieldDescLines)
+							Console.WriteLine("\t# {0}", line);
 				}
 			}
-			Console.WriteLine("\n```");
+
+			Console.WriteLine();
+			Console.WriteLine("```");
 		}
 	}
 }