From a25aa23805f655c0b2cd0a3a4ae1f6d1043ddac4 Mon Sep 17 00:00:00 2001 From: Scott_NZ Date: Fri, 22 Mar 2013 18:12:47 +1300 Subject: [PATCH] radoc tidy --- OpenRA.FileFormats/FieldLoader.cs | 4 +- OpenRA.Game/GameRules/ActorInfo.cs | 12 ++--- OpenRA.Mods.RA/Attack/AttackMedic.cs | 6 +-- OpenRA.Mods.RA/Capturable.cs | 3 +- OpenRA.Mods.RA/FreeActor.cs | 9 ++-- OpenRA.Mods.RA/GivesExperience.cs | 2 +- .../Player/ClassicProductionQueue.cs | 18 ++++---- OpenRA.Mods.RA/Player/ProductionQueue.cs | 29 ++++++------ OpenRA.Utility/Command.cs | 46 +++++++++++-------- 9 files changed, 66 insertions(+), 63 deletions(-) diff --git a/OpenRA.FileFormats/FieldLoader.cs b/OpenRA.FileFormats/FieldLoader.cs index f0e0e0c205..453756a306 100755 --- a/OpenRA.FileFormats/FieldLoader.cs +++ b/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 DescAttribute(string description) { Description = description; } + public readonly string[] Lines; + public DescAttribute(params string[] lines) { Lines = lines; } } } diff --git a/OpenRA.Game/GameRules/ActorInfo.cs b/OpenRA.Game/GameRules/ActorInfo.cs index c7333361d5..2906e58886 100644 --- a/OpenRA.Game/GameRules/ActorInfo.cs +++ b/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" + - "\t# Special actors like world or player are usually defined in system.yaml and effect everything.")] + [Desc("A unit/building inside the game. Every rules starts with one and adds trait to it.", + "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" + - "\t# Also if you add an ^ in front of the name, the engine will recognize this as a collection of traits\n" + - "\t# 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.")] + [Desc("The actor name can be anything, but the sprites used in the Render*: traits default to this one.", + "If you add an ^ in front of the name, the engine will recognize this as a collection of traits", + "that can be inherited by others (using Inherits:) and not a real unit.", + "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(); diff --git a/OpenRA.Mods.RA/Attack/AttackMedic.cs b/OpenRA.Mods.RA/Attack/AttackMedic.cs index c557533ca4..6261d6745c 100644 --- a/OpenRA.Mods.RA/Attack/AttackMedic.cs +++ b/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" + - "\t# It conflicts with any other weapon or Attack*: trait because it will hurt friendlies during the\n" + - "\t# heal process then. It also won't work with buildings (use RepairsUnits: for them).")] + [Desc("Give the unit a \"heal-weapon\".", + "It conflicts with any other weapon or Attack*: trait because it will hurt friendlies during the", + "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 ); } diff --git a/OpenRA.Mods.RA/Capturable.cs b/OpenRA.Mods.RA/Capturable.cs index c6e9533c33..8ce3cce153 100644 --- a/OpenRA.Mods.RA/Capturable.cs +++ b/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" + - "\t# It stays neutral during this period. You might want to add a CapturableBar: trait, too.")] + [Desc("Seconds it takes to change the owner.", "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); } diff --git a/OpenRA.Mods.RA/FreeActor.cs b/OpenRA.Mods.RA/FreeActor.cs index 3381a20962..cab41feb88 100644 --- a/OpenRA.Mods.RA/FreeActor.cs +++ b/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" + - "\t # If you want more then one unit to appear copy this section and assign IDs like FreeActor@2, ...")] + [Desc("Player recives a unit for free once the building is placed. This also works for structures.", + "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" + - "\t # it will break, when you add FindResources here.")] + [Desc("What the unit should start doing. Warning: If this is not a harvester", "it will break if you use FindResources.")] public readonly string InitialActivity = null; [Desc("Offset relative to structure-center in 2D (e.g. 1, 2)")] public readonly int2 SpawnOffset = int2.Zero; diff --git a/OpenRA.Mods.RA/GivesExperience.cs b/OpenRA.Mods.RA/GivesExperience.cs index ab5dadbc06..ee8baa2287 100644 --- a/OpenRA.Mods.RA/GivesExperience.cs +++ b/OpenRA.Mods.RA/GivesExperience.cs @@ -15,7 +15,7 @@ namespace OpenRA.Mods.RA { class GivesExperienceInfo : TraitInfo { - [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; } diff --git a/OpenRA.Mods.RA/Player/ClassicProductionQueue.cs b/OpenRA.Mods.RA/Player/ClassicProductionQueue.cs index 62810ffe98..27c470e19e 100755 --- a/OpenRA.Mods.RA/Player/ClassicProductionQueue.cs +++ b/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" + - "\t# Will only work together with the Production: trait on the actor that actually does the production.\n" + - "\t# You will also want to add PrimaryBuildings: to let the user choose where new units should exit.")] + [Desc("Attach this to the world actor (not a building!) to define a new shared build queue.", + "Will only work together with the Production: trait on the actor that actually does the production.", + "You will also want to add PrimaryBuildings: to let the user choose where new units should exit.")] public class ClassicProductionQueueInfo : ProductionQueueInfo, Requires, Requires, Requires { - [Desc("If you build more actors of the same type, \n" + - "\t# the same queue will get it's build time lowered for every actor produced there.")] + [Desc("If you build more actors of the same type,", "the same queue will get its build time lowered for every actor produced there.")] public readonly bool SpeedUp = false; - [Desc("Everytime another production building of the same queue is\n" + - "\t# contructed, the build time of all actors in the queue\n" + - "\t#get divided by this value.")] + [Desc("Every time another production building of the same queue is", + "contructed, the build times of all actors in the queue", + "are divided by this value.")] public readonly int BuildTimeSpeedUpDivisor = 2; - [Desc("You can still build more production buildings\n" + - "\t# than this value, but the build time won't increase further.")] + [Desc("You can still build more production buildings", "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); } diff --git a/OpenRA.Mods.RA/Player/ProductionQueue.cs b/OpenRA.Mods.RA/Player/ProductionQueue.cs index b107d9a50f..42bde6cbf8 100755 --- a/OpenRA.Mods.RA/Player/ProductionQueue.cs +++ b/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" + - "\t# If one builds another actor of this type, he will get a separate queue to create two actors\n" + - "\t# at the same time. Will only work together with the Production: trait.")] + [Desc("Attach this to an actor (usually a building) to let it produce units or construct buildings.", + "If one builds another actor of this type, he will get a separate queue to create two actors", + "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" + - "\t# The filename of the audio is defined per faction in notifications.yaml.")] + [Desc("Notification played when production is complete.", + "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" + - "\t# when the build limit exceeded or the exit is jammed.\n" + - "\t# The filename of the audio is defined per faction in notifications.yaml.")] + [Desc("Notification played when you can't train another unit", + "when the build limit exceeded or the exit is jammed.", + "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" + - "\t# The filename of the audio is defined per faction in notifications.yaml.")] + [Desc("Notification played when user clicks on the build palette icon.", + "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" + - "\t# on the build palette icon. The filename of the audio is defined per faction in notifications.yaml.")] + [Desc("Notification played when player right-clicks on the build palette icon.", + "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" + - "\t# on a build palette icon that is already on hold.\n" + - "\t# The filename of the audio is defined per faction in notifications.yaml.")] + [Desc("Notification played when player right-clicks on a build palette icon that is already on hold.", + "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); } diff --git a/OpenRA.Utility/Command.cs b/OpenRA.Utility/Command.cs index 53e320683f..b357c122c2 100644 --- a/OpenRA.Utility/Command.cs +++ b/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("```yaml\n\n"); + 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.", DateTime.Now); + Console.WriteLine("```yaml"); + Console.WriteLine(); - foreach(var t in Game.modData.ObjectCreator.GetTypesImplementing()) + foreach (var t in Game.modData.ObjectCreator.GetTypesImplementing()) { if (t.ContainsGenericParameters || t.IsAbstract) - continue; // skip helpers like TraitInfo + continue; // skip helpers like TraitInfo - var traitName = t.Name.Replace("Info",""); - var traitDesc = t.GetCustomAttributes(false).Select(a => a.Description).FirstOrDefault(); - if (!string.IsNullOrEmpty(traitDesc)) - traitDesc = " # {0}".F(traitDesc); + var traitName = t.Name.EndsWith("Info") ? t.Name.Substring(0, t.Name.Length - 4) : t.Name; + var traitDescLines = t.GetCustomAttributes(false).SelectMany(d => d.Lines); + Console.WriteLine("{0}:{1}", traitName, traitDescLines.Count() == 1 ? " # " + traitDescLines.First() : ""); + 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(true).Select(a => a.Description).FirstOrDefault(); - if (!string.IsNullOrEmpty(fieldDesc)) - fieldDesc = ", {0}".F(fieldDesc); - var fieldType = NiceTypeName(f.FieldType); + var fieldDescLines = f.GetCustomAttributes(true).SelectMany(d => d.Lines); + var fieldType = FriendlyTypeName(f.FieldType); var defaultValue = FieldSaver.SaveField(liveTraitInfo, f.Name).Value.Value; - - Console.WriteLine("\t\t{0}: {2} # Type: {1}{3}", f.Name, fieldType, defaultValue, fieldDesc); + Console.WriteLine("\t{0}: {1} # Type: {2}{3}", f.Name, defaultValue, fieldType, fieldDescLines.Count() == 1 ? ". " + fieldDescLines.First() : ""); + if (fieldDescLines.Count() >= 2) + foreach (var line in fieldDescLines) + Console.WriteLine("\t# {0}", line); } } - Console.WriteLine("\n```"); + + Console.WriteLine(); + Console.WriteLine("```"); } } }