Add weapon rules documentation.

.gitignore

@@ -62,6 +62,7 @@ OpenRA.Launcher.Mac/OpenRA.xcodeproj/*.mode1v3
 
 # auto-generated documentation
 DOCUMENTATION.md
+WEAPONS.md
 Lua-API.md
 *.html
 openra.6

OpenRA.Mods.Common/OpenRA.Mods.Common.csproj

@@ -553,6 +553,7 @@
     <Compile Include="UtilityCommands\ExtractSettingsDocsCommand.cs" />
     <Compile Include="UtilityCommands\ExtractZeroBraneStudioLuaAPI.cs" />
     <Compile Include="UtilityCommands\ExtractTraitDocsCommand.cs" />
+    <Compile Include="UtilityCommands\ExtractWeaponDocsCommand.cs" />
     <Compile Include="Widgets\Logic\Ingame\MusicControllerLogic.cs" />
     <Compile Include="Widgets\UnitCommandWidget.cs" />
     <Compile Include="WorldExtensions.cs" />

OpenRA.Mods.Common/Util.cs

@@ -201,7 +201,10 @@ namespace OpenRA.Mods.Common
 				return "Mapping of {0} to {1}".F(t.GetGenericArguments().Select(FriendlyTypeName).ToArray());
 
 			if (t.IsSubclassOf(typeof(Array)))
-				return "Multiple {0}".F(FriendlyTypeName(t.GetElementType()));
+				return "Collection of {0}".F(FriendlyTypeName(t.GetElementType()));
+
+			if (t.IsGenericType && t.GetGenericTypeDefinition().GetInterfaces().Any(e => e.IsGenericType && e.GetGenericTypeDefinition() == typeof(IEnumerable<>)))
+				return "Collection of {0}".F(FriendlyTypeName(t.GetGenericArguments().First()));
 
 			if (t == typeof(int) || t == typeof(uint))
 				return "Integer";
@@ -239,6 +242,12 @@ namespace OpenRA.Mods.Common
 			if (t == typeof(HSLColor) || t == typeof(Color))
 				return "Color (RRGGBB[AA] notation)";
 
+			if (t == typeof(IProjectileInfo))
+				return "Projectile";
+
+			if (t == typeof(IWarhead))
+				return "Warhead";
+
 			return t.Name;
 		}
 	}

OpenRA.Mods.Common/UtilityCommands/ExtractWeaponDocsCommand.cs

@@ -0,0 +1,106 @@
+#region Copyright & License Information
+/*
+ * Copyright 2007-2017 The OpenRA Developers (see AUTHORS)
+ * This file is part of OpenRA, which is free software. It is made
+ * available to you under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version. For more
+ * information, see COPYING.
+ */
+#endregion
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using OpenRA.GameRules;
+using OpenRA.Traits;
+
+namespace OpenRA.Mods.Common.UtilityCommands
+{
+	class ExtractWeaponDocsCommand : IUtilityCommand
+	{
+		string IUtilityCommand.Name { get { return "--weapon-docs"; } }
+
+		bool IUtilityCommand.ValidateArguments(string[] args)
+		{
+			return true;
+		}
+
+		[Desc("Generate weaponry documentation in MarkDown format.")]
+		void IUtilityCommand.Run(Utility utility, string[] args)
+		{
+			// HACK: The engine code assumes that Game.modData is set.
+			Game.ModData = utility.ModData;
+
+			Console.WriteLine(
+				"This documentation is aimed at modders. It displays a template for weapon definitions " +
+				"as well as its contained types (warheads and projectiles) 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 for version {0} of OpenRA.", utility.ModData.Manifest.Metadata.Version);
+			Console.WriteLine();
+
+			var toc = new StringBuilder();
+			var doc = new StringBuilder();
+
+			var currentNamespace = "";
+
+			var objectCreator = utility.ModData.ObjectCreator;
+			var weaponInfo = objectCreator.GetTypesImplementing<WeaponInfo>();
+			var warheads = objectCreator.GetTypesImplementing<IWarhead>().OrderBy(t => t.Namespace);
+			var projectiles = objectCreator.GetTypesImplementing<IProjectileInfo>().OrderBy(t => t.Namespace);
+
+			var weaponTypes = Enumerable.Concat(weaponInfo, Enumerable.Concat(projectiles, warheads));
+			foreach (var t in weaponTypes)
+			{
+				// skip helpers like TraitInfo<T>
+				if (t.ContainsGenericParameters || t.IsAbstract)
+					continue;
+
+				if (currentNamespace != t.Namespace)
+				{
+					currentNamespace = t.Namespace;
+					doc.AppendLine();
+					doc.AppendLine("## {0}".F(currentNamespace));
+					toc.AppendLine("* [{0}](#{1})".F(currentNamespace, currentNamespace.Replace(".", "").ToLowerInvariant()));
+				}
+
+				var traitName = t.Name.EndsWith("Info") ? t.Name.Substring(0, t.Name.Length - 4) : t.Name;
+				toc.AppendLine(" * [{0}](#{1})".F(traitName, traitName.ToLowerInvariant()));
+				doc.AppendLine();
+				doc.AppendLine("### {0}".F(traitName));
+
+				var traitDescLines = t.GetCustomAttributes<DescAttribute>(false).SelectMany(d => d.Lines);
+				foreach (var line in traitDescLines)
+					doc.AppendLine(line);
+
+				var infos = FieldLoader.GetTypeLoadInfo(t);
+				if (!infos.Any())
+					continue;
+
+				doc.AppendLine("<table>");
+				doc.AppendLine("<tr><th>Property</th><th>Default Value</th><th>Type</th><th>Description</th></tr>");
+
+				var liveTraitInfo = t == typeof(WeaponInfo) ? null : objectCreator.CreateBasic(t);
+				foreach (var info in infos)
+				{
+					var fieldDescLines = info.Field.GetCustomAttributes<DescAttribute>(true).SelectMany(d => d.Lines);
+					var fieldType = Util.FriendlyTypeName(info.Field.FieldType);
+					var defaultValue = liveTraitInfo == null ? "" : FieldSaver.SaveField(liveTraitInfo, info.Field.Name).Value.Value;
+					doc.Append("<tr><td>{0}</td><td>{1}</td><td>{2}</td>".F(info.YamlName, defaultValue, fieldType));
+					doc.Append("<td>");
+
+					foreach (var line in fieldDescLines)
+						doc.Append(line + " ");
+
+					doc.AppendLine("</td></tr>");
+				}
+
+				doc.AppendLine("</table>");
+			}
+
+			Console.Write(toc.ToString());
+			Console.Write(doc.ToString());
+		}
+	}
+}

make.ps1

@@ -193,6 +193,7 @@ function Docs-Command
 	{
 		./make.ps1 version
 		./OpenRA.Utility.exe all --docs | Out-File -Encoding "UTF8" DOCUMENTATION.md
+		./OpenRA.Utility.exe all --weapon-docs | Out-File -Encoding "UTF8" WEAPONS.md
 		./OpenRA.Utility.exe all --lua-docs | Out-File -Encoding "UTF8" Lua-API.md
 	}
 	else

packaging/update-wiki.sh

@@ -28,6 +28,7 @@ rm -rf $HOME/openra-wiki
 git clone git@github.com:OpenRA/OpenRA.wiki.git $HOME/openra-wiki
 
 mono --debug ../OpenRA.Utility.exe all --docs > "${HOME}/openra-wiki/Traits${TAG}.md"
+mono --debug ../OpenRA.Utility.exe all --weapon-docs > "${HOME}/openra-wiki/Weapons${TAG}.md"
 mono --debug ../OpenRA.Utility.exe all --lua-docs > "${HOME}/openra-wiki/Lua API${TAG}.md"
 
 pushd $HOME/openra-wiki