AI macros: update comments for display on wiki reference page

This is for the auto-generated page at
http://www.wesnoth.org/macro-reference.html

data/core/macros/ai.cfg

@@ -513,6 +513,9 @@
 ############################################################
 
 #define EXPERIMENTAL_AI
+    # Experimental AI with alternative recruitment, castle switching, alternative retreating,
+    # village grabbing, poison spreading, healer placement, village hunting and
+    # move-to-enemy candidate actions.
     # Put this into the [side][ai] tag.
     # Does not work in [modify_side][ai] or [modify_ai] at the moment.
     version=10710

data/core/macros/ai_candidate_actions.cfg

@@ -50,6 +50,7 @@
 # well-known candidate actions
 
 #define AI_CA_GOTO
+    # RCA AI candidate action: goto
     [candidate_action]
         id=goto
         engine=cpp
@@ -60,6 +61,7 @@
 #enddef
 
 #define AI_CA_RECRUITMENT
+    # RCA AI candidate action: recruitment
     [candidate_action]
         id=recruitment
         engine=cpp
@@ -70,6 +72,7 @@
 #enddef
 
 #define AI_CA_MOVE_LEADER_TO_GOALS
+    # RCA AI candidate action: move_leader_to_goals
     [candidate_action]
         id=move_leader_to_goals
         engine=cpp
@@ -80,6 +83,7 @@
 #enddef
 
 #define AI_CA_MOVE_LEADER_TO_KEEP
+    # RCA AI candidate action: move_leader_to_keep
     [candidate_action]
         id=move_leader_to_keep
         engine=cpp
@@ -90,6 +94,7 @@
 #enddef
 
 #define AI_CA_COMBAT
+    # RCA AI candidate action: combat
     [candidate_action]
         id=combat
         engine=cpp
@@ -100,6 +105,7 @@
 #enddef
 
 #define AI_CA_HEALING
+    # RCA AI candidate action: healing
     [candidate_action]
         id=healing
         engine=cpp
@@ -110,6 +116,7 @@
 #enddef
 
 #define AI_CA_VILLAGES
+    # RCA AI candidate action: villages
     [candidate_action]
         id=villages
         engine=cpp
@@ -120,6 +127,7 @@
 #enddef
 
 #define AI_CA_RETREAT
+    # RCA AI candidate action: retreat
     [candidate_action]
         id=retreat
         engine=cpp
@@ -130,6 +138,7 @@
 #enddef
 
 #define AI_CA_MOVE_TO_TARGETS
+    # RCA AI candidate action: move_to_targets
     [candidate_action]
         id=move_to_targets
         engine=cpp
@@ -140,6 +149,7 @@
 #enddef
 
 #define AI_CA_LEADER_SHARES_KEEP
+    # RCA AI candidate action: leader_shares_keep
     [candidate_action]
         id=leader_shares_keep
         engine=cpp
@@ -157,6 +167,7 @@
 # extra candidate actions
 
 #define AI_CA_SIMPLE_MOVE_TO_TARGETS
+    # Extra candidate action: simple_move_to_targets
     [candidate_action]
         id=simple_move_to_targets
         engine=cpp
@@ -167,8 +178,7 @@
 #enddef
 
 #define AI_CA_POISONING
-    # candidate action for poisoners to spread poison around
-
+    # Extra candidate action: Formula AI CA for poisoners to spread poison around
     [candidate_action]
         engine=fai
         id=poisoning

data/core/macros/ai_controller.cfg

@@ -1,7 +1,7 @@
 #textdomain wesnoth
 
 #define AI_CONTROLLER_ALLOW_UNIT_CONTROL CONTROLLER_SIDE UNIT_ID
-
+    # Right-click content menu item for issuing instructions to an allied AI unit
     [store_unit]
         [filter]
             id={UNIT_ID}
@@ -54,7 +54,7 @@
 #enddef
 
 #define AI_CONTROLLER_ALLOW_LEADER_CONTROL CONTROLLER_SIDE CONTROLLED_SIDE
-
+    # Right-click content menu item for issuing instructions to an allied AI side's leader
     [store_unit]
         [filter]
             side={CONTROLLED_SIDE}
@@ -105,12 +105,14 @@
 #enddef
 
 #define AI_CONTROLLER_NOTE
+    # Note for the objectives that instructions can be issued to an allied AI side
     [note]
         description= _ "In this scenario, you may issue instructions to an allied side by right-clicking on a unit that belongs to it."
     [/note]
 #enddef
 
 #define AI_CONTROLLER AFFIX PLAYER_SIDES ALLY_SIDES VARIABLES_WML
+    # Right-click content menu item for issuing instructions to an allied AI side
     [event]
         name=prestart
 

data/core/macros/ai_micro_ais.cfg

@@ -1,8 +1,11 @@
 #textdomain wesnoth-ai
 
+# These macros are here just for backward compatibility, we will get rid of the entire
+# file eventually as no Micro AI engine macros are needed any more.
+# Note: These macros go into the [side] tag, so ActionWML tags cannot be used, that's why
+# the deprecation message is set up the way it is.
+
 #define MAI_MACRO_DEPRECATION MACRO_NAME
-    # Somewhat hacky way to get a deprecation message displayed
-    # This macro goes into the [side] tag, so ActionWML tags cannot be used
     [unit]
         type=Fog Clearer
         x,y=1,1