Add Lua documentation details

OpenRA.Mods.Cnc/Scripting/Properties/ChronosphereProperties.cs

@@ -23,7 +23,8 @@ namespace OpenRA.Mods.Cnc.Scripting
 		public ChronosphereProperties(ScriptContext context, Actor self)
 			: base(context, self) { }
 
-		[Desc("Chronoshift a group of actors. A duration of 0 will teleport the actors permanently.")]
+		[Desc("Chronoshift a group of actors. A duration of 0 will teleport the actors permanently. " +
+			"If a given cell is unexplored for this power's owner, the closest valid cell will be used instead.")]
 		public void Chronoshift([ScriptEmmyTypeOverride("{ [actor]: cpos }")] LuaTable unitLocationPairs, int duration = 0, bool killCargo = false)
 		{
 			foreach (var kv in unitLocationPairs)

OpenRA.Mods.Common/Scripting/Global/TriggerGlobal.cs

@@ -82,7 +82,8 @@ namespace OpenRA.Mods.Common.Scripting
 			GetScriptTriggers(actor).RegisterCallback(Trigger.OnIdle, func, Context);
 		}
 
-		[Desc("Call a function when the actor is damaged. The callback " +
+		[Desc("Call a function when the actor is damaged. " +
+			"Repairs or other negative damage can activate this trigger. The callback " +
 			"function will be called as func(self: actor, attacker: actor, damage: integer).")]
 		public void OnDamaged(Actor actor, [ScriptEmmyTypeOverride("fun(self: actor, attacker: actor, damage: integer)")] LuaFunction func)
 		{
@@ -130,7 +131,8 @@ namespace OpenRA.Mods.Common.Scripting
 				GetScriptTriggers(a).OnKilledInternal += OnMemberKilled;
 		}
 
-		[Desc("Call a function when one of the actors in a group is killed. The callback " +
+		[Desc("Call a function when one of the actors in a group is killed. " +
+			"This trigger is only called once. The callback " +
 			"function will be called as func(killed: actor).")]
 		public void OnAnyKilled(Actor[] actors, [ScriptEmmyTypeOverride("fun(killed: actor)")] LuaFunction func)
 		{
@@ -164,12 +166,12 @@ namespace OpenRA.Mods.Common.Scripting
 
 		[Desc("Call a function when this actor produces another actor. " +
 			"The callback function will be called as func(producer: actor, produced: actor).")]
-		public void OnProduction(Actor actors, [ScriptEmmyTypeOverride("fun(producer: actor, produced: actor)")] LuaFunction func)
+		public void OnProduction(Actor actor, [ScriptEmmyTypeOverride("fun(producer: actor, produced: actor)")] LuaFunction func)
 		{
-			if (actors == null)
+			if (actor == null)
-				throw new NullReferenceException(nameof(actors));
+				throw new NullReferenceException(nameof(actor));
 
-			GetScriptTriggers(actors).RegisterCallback(Trigger.OnProduction, func, Context);
+			GetScriptTriggers(actor).RegisterCallback(Trigger.OnProduction, func, Context);
 		}
 
 		[Desc("Call a function when any actor produces another actor. The callback " +
@@ -304,15 +306,16 @@ namespace OpenRA.Mods.Common.Scripting
 
 		[Desc("Call a function when this actor is captured. The callback function " +
 			"will be called as func(self: actor, captor: actor, oldOwner: player, newOwner: player).")]
-		public void OnCapture(Actor actors, [ScriptEmmyTypeOverride("fun(self: actor, captor: actor, oldOwner: player, newOwner: player)")] LuaFunction func)
+		public void OnCapture(Actor actor, [ScriptEmmyTypeOverride("fun(self: actor, captor: actor, oldOwner: player, newOwner: player)")] LuaFunction func)
 		{
-			if (actors == null)
+			if (actor == null)
-				throw new NullReferenceException(nameof(actors));
+				throw new NullReferenceException(nameof(actor));
 
-			GetScriptTriggers(actors).RegisterCallback(Trigger.OnCapture, func, Context);
+			GetScriptTriggers(actor).RegisterCallback(Trigger.OnCapture, func, Context);
 		}
 
 		[Desc("Call a function when this actor is killed or captured. " +
+			"This trigger is only called once. " +
 			"The callback function will be called as func().")]
 		public void OnKilledOrCaptured(Actor actor, [ScriptEmmyTypeOverride("fun()")] LuaFunction func)
 		{
@@ -345,6 +348,7 @@ namespace OpenRA.Mods.Common.Scripting
 		}
 
 		[Desc("Call a function when all of the actors in a group have been killed or captured. " +
+			"This trigger is only called once. " +
 			"The callback function will be called as func().")]
 		public void OnAllKilledOrCaptured(Actor[] actors, [ScriptEmmyTypeOverride("fun()")] LuaFunction func)
 		{

OpenRA.Mods.Common/Scripting/Properties/GeneralProperties.cs

@@ -80,7 +80,8 @@ namespace OpenRA.Mods.Common.Scripting
 			Self.World.Add(new FlashTarget(Self, color, 0.5f, count, interval, delay));
 		}
 
-		[Desc("The effective owner of the actor.")]
+		[Desc("The effective (displayed) owner of the actor. " +
+			"This may differ from the true owner in some cases, such as disguised actors.")]
 		public Player EffectiveOwner
 		{
 			get

OpenRA.Mods.Common/Scripting/Properties/MissionObjectiveProperties.cs

@@ -68,7 +68,8 @@ namespace OpenRA.Mods.Common.Scripting
 		[ScriptActorPropertyActivity]
 		[Desc("Mark an objective as failed.  This needs the objective ID returned " +
 			"by AddObjective as argument.  Secondary objectives do not have any " +
-			"influence whatsoever on the outcome of the game.")]
+			"influence whatsoever on the outcome of the game. " +
+			"It is possible to mark a completed objective as a failure.")]
 		public void MarkFailedObjective(int id)
 		{
 			if (id < 0 || id >= mo.Objectives.Count)