Codefix: broken links and syntax issues in script API documentation

src/script/api/doxygen_filter.awk

@@ -24,7 +24,10 @@ BEGIN {
 }
 
 {
+	# replace Script with AI/GS, except for ScriptErrorType
 	gsub(/Script/, api)
+	gsub(/AIErrorType/, "ScriptErrorType")
+	gsub(/GSErrorType/, "ScriptErrorType")
 }
 
 {
@@ -245,7 +248,7 @@ BEGIN {
 }
 
 # Add a const (non-enum) value
-/^[ 	]*static const \w+ \w+ = -?\(?\w*\)?\w+;/ {
+/^[ 	]*static const \w+ \w+ = [^;]+;/ {
 	if (api_selected == "") api_selected = cls_in_api
 	if (api_selected == "false") {
 		api_selected = ""

src/script/api/script_companymode.hpp

@@ -52,7 +52,7 @@ public:
 	 * Check whether a company mode is valid. In other words, are commands
 	 * being executed under some company and does the company still exist?
 	 * @return true When a company mode is valid.
-	 * @post !ScriptCompanyMode::IsDeity().
+	 * @post If IsValid() is true, then IsDeity() is false.
 	 */
 	static bool IsValid();
 
@@ -60,7 +60,7 @@ public:
 	 * Check whether the company mode is not active, i.e. whether we are a deity.
 	 * In other words, are commands are not being executed under some company.
 	 * @return true When we are a deity, i.e. company mode is not active.
-	 * @post !ScriptCompanyMode::IsValid().
+	 * @post if IsDeity() is true, then IsValid() is false.
 	 */
 	static bool IsDeity();
 };

src/script/api/script_grouplist.hpp

@@ -29,20 +29,22 @@ public:
 	/**
 	 * Apply a filter when building the list.
 	 * @param filter_function The function which will be doing the filtering.
-	 * @param params The params to give to the filters (minus the first param,
+	 * @param ... The params to give to the filters (minus the first param,
 	 *  which is always the index-value).
 	 * @game @pre ScriptCompanyMode::IsValid().
 	 * @note You can write your own filters and use them. Just remember that
 	 *  the first parameter should be the index-value, and it should return
 	 *  a bool.
 	 * @note Example:
+	 * @code
 	 *  function IsType(group_id, type)
 	 *  {
 	 *    return ScriptGroup.GetVehicleType(group_id) == type;
 	 *  }
-	 *  ScriptGroupList(IsType, ScriptVehicle.VT_ROAD);
+	 *  local rv_groups = ScriptGroupList(IsType, ScriptVehicle.VT_ROAD);
+	 * @endcode
 	 */
-	ScriptGroupList(void *filter_function, int params, ...);
+	ScriptGroupList(function filter_function, ...);
 #else
 	/**
 	 * The constructor wrapper from Squirrel.

src/script/api/script_industrylist.hpp

@@ -25,20 +25,23 @@ public:
 	/**
 	 * Apply a filter when building the list.
 	 * @param filter_function The function which will be doing the filtering.
-	 * @param params The params to give to the filters (minus the first param,
+	 * @param ... The params to give to the filters (minus the first param,
 	 *  which is always the index-value).
 	 * @note You can write your own filters and use them. Just remember that
 	 *  the first parameter should be the index-value, and it should return
 	 *  a bool.
 	 * @note Example:
-	 *  ScriptIndustryList(ScriptIndustry.HasDock);
+	 * @code
+	 *  local water_industries = ScriptIndustryList(ScriptIndustry.HasDock);
+	 *
 	 *  function IsType(industry_id, type)
 	 *  {
 	 *    return ScriptIndustry.GetIndustryType(industry_id) == type;
 	 *  }
-	 *  ScriptIndustryList(IsType, 0);
+	 *  local industries = ScriptIndustryList(IsType, 0);
+	 * @endcode
 	 */
-	ScriptIndustryList(void *filter_function, int params, ...);
+	ScriptIndustryList(function filter_function, ...);
 #else
 	/**
 	 * The constructor wrapper from Squirrel.

src/script/api/script_league.cpp

@@ -49,7 +49,7 @@
 	return ::LeagueTableElement::IsValidID(element_id);
 }
 
-/* static */ ScriptLeagueTable::LeagueTableElementID ScriptLeagueTable::NewElement(ScriptLeagueTable::LeagueTableID table, SQInteger rating, ScriptCompany::CompanyID company, Text *text, Text *score, LinkType link_type, LinkTargetID link_target)
+/* static */ ScriptLeagueTable::LeagueTableElementID ScriptLeagueTable::NewElement(ScriptLeagueTable::LeagueTableID table, SQInteger rating, ScriptCompany::CompanyID company, Text *text, Text *score, LinkType link_type, SQInteger link_target)
 {
 	CCountedPtr<Text> text_counter(text);
 	CCountedPtr<Text> score_counter(score);
@@ -78,7 +78,7 @@
 	return (ScriptLeagueTable::LeagueTableElementID)0;
 }
 
-/* static */ bool ScriptLeagueTable::UpdateElementData(LeagueTableElementID element, ScriptCompany::CompanyID company, Text *text, LinkType link_type, LinkTargetID link_target)
+/* static */ bool ScriptLeagueTable::UpdateElementData(LeagueTableElementID element, ScriptCompany::CompanyID company, Text *text, LinkType link_type, SQInteger link_target)
 {
 	CCountedPtr<Text> text_counter(text);
 

src/script/api/script_league.hpp

@@ -92,7 +92,7 @@ public:
 	 * @pre score != null && len(score) != 0.
 	 * @pre IsValidLink(Link(link_type, link_target)).
 	 */
-	static LeagueTableElementID NewElement(LeagueTableID table, SQInteger rating, ScriptCompany::CompanyID company, Text *text, Text *score, LinkType link_type, LinkTargetID link_target);
+	static LeagueTableElementID NewElement(LeagueTableID table, SQInteger rating, ScriptCompany::CompanyID company, Text *text, Text *score, LinkType link_type, SQInteger link_target);
 
 	/**
 	 * Update the attributes of a league table element.
@@ -107,7 +107,7 @@ public:
 	 * @pre text != null && len(text) != 0.
 	 * @pre IsValidLink(Link(link_type, link_target)).
 	 */
-	static bool UpdateElementData(LeagueTableElementID element, ScriptCompany::CompanyID company, Text *text, LinkType link_type, LinkTargetID link_target);
+	static bool UpdateElementData(LeagueTableElementID element, ScriptCompany::CompanyID company, Text *text, LinkType link_type, SQInteger link_target);
 
 	/**
 	 * Create a new league table element.

src/script/api/script_list.hpp

@@ -370,7 +370,7 @@ public:
 	/**
 	 * Give all items a value defined by the valuator you give.
 	 * @param valuator_function The function which will be doing the valuation.
-	 * @param params The params to give to the valuators (minus the first param,
+	 * @param ... The params to give to the valuators (minus the first param,
 	 *  which is always the index-value we are valuating).
 	 * @note You may not add, remove or change (setting the value of) items while
 	 *  valuating. You may also not (re)sort while valuating.
@@ -378,6 +378,7 @@ public:
 	 *  the first parameter should be the index-value, and it should return
 	 *  an integer.
 	 * @note Example:
+	 * @code
 	 *  list.Valuate(ScriptBridge.GetPrice, 5);
 	 *  list.Valuate(ScriptBridge.GetMaxLength);
 	 *  function MyVal(bridge_id, myparam)
@@ -385,8 +386,9 @@ public:
 	 *    return myparam * bridge_id; // This is silly
 	 *  }
 	 *  list.Valuate(MyVal, 12);
+	 * @endcode
 	 */
-	void Valuate(void *valuator_function, int params, ...);
+	void Valuate(function valuator_function, ...);
 #endif /* DOXYGEN_API */
 };
 

src/script/api/script_signlist.hpp

@@ -25,20 +25,22 @@ public:
 	/**
 	 * Apply a filter when building the list.
 	 * @param filter_function The function which will be doing the filtering.
-	 * @param params The params to give to the filters (minus the first param,
+	 * @param ... The params to give to the filters (minus the first param,
 	 *  which is always the index-value).
 	 * @note You can write your own filters and use them. Just remember that
 	 *  the first parameter should be the index-value, and it should return
 	 *  a bool.
 	 * @note Example:
+	 * @code
 	 *  function Contains(sign_id, str)
 	 *  {
 	 *    local name = ScriptSign.GetName(sign_id);
 	 *    return name != null && name.find(str) != null;
 	 *  }
-	 *  ScriptSignList(Contains, "something");
+	 *  local signs = ScriptSignList(Contains, "something");
+	 * @endcode
 	 */
-	ScriptSignList(void *filter_function, int params, ...);
+	ScriptSignList(function filter_function, ...);
 #else
 	ScriptSignList(HSQUIRRELVM);
 #endif /* DOXYGEN_API */

src/script/api/script_story_page.hpp

@@ -203,8 +203,8 @@ public:
 	 * @param reference A reference value to the object that is referred to by some page element types.
 	 *                  When type is SPET_GOAL, this is the goal ID.
 	 *                  When type is SPET_LOCATION, this is the TileIndex.
-	 *                  When type is a button, this is additional parameters for the button,
-	 *                  use the #BuildPushButtonReference, #BuildTileButtonReference, or #BuildVehicleButtonReference functions to make the values.
+	 *                  When type is a button, this is the ID returned by
+	 *                  #MakePushButtonReference, #MakeTileButtonReference, or #MakeVehicleButtonReference.
 	 * @param text The body text of page elements that allow custom text. (SPET_TEXT and SPET_LOCATION)
 	 * @return The new StoryPageElementID, or STORY_PAGE_ELEMENT_INVALID if it failed.
 	 * @pre ScriptCompanyMode::IsDeity().
@@ -329,14 +329,14 @@ public:
 
 	/**
 	* Check whether this is a valid story page button flag.
-	* @param colour The StoryPageButtonFlags to check.
+	* @param flags The StoryPageButtonFlags to check.
 	* @return True if and only if this story page button flag is valid.
 	*/
 	static bool IsValidStoryPageButtonFlags(StoryPageButtonFlags flags);
 
 	/**
 	 * Check whether this is a valid story page button cursor.
-	 * @param colour The StoryPageButtonCursor to check.
+	 * @param cursor The StoryPageButtonCursor to check.
 	 * @return True if and only if this story page button cursor is valid.
 	 */
 	static bool IsValidStoryPageButtonCursor(StoryPageButtonCursor cursor);

src/script/api/script_subsidylist.hpp

@@ -25,19 +25,21 @@ public:
 	/**
 	 * Apply a filter when building the list.
 	 * @param filter_function The function which will be doing the filtering.
-	 * @param params The params to give to the filters (minus the first param,
+	 * @param ... The params to give to the filters (minus the first param,
 	 *  which is always the index-value).
 	 * @note You can write your own filters and use them. Just remember that
 	 *  the first parameter should be the index-value, and it should return
 	 *  a bool.
 	 * @note Example:
+	 * @code
 	 *  function IsType(subsidy_id, type)
 	 *  {
 	 *    return ScriptSubsidy.GetSourceType(subsidy_id) == type;
 	 *  }
-	 *  ScriptSubsidyList(IsType, ScriptSubsidy.SPT_TOWN);
+	 *  local town_subs = ScriptSubsidyList(IsType, ScriptSubsidy.SPT_TOWN);
+	 * @endcode
 	 */
-	ScriptSubsidyList(void *filter_function, int params, ...);
+	ScriptSubsidyList(function filter_function, ...);
 #else
 	ScriptSubsidyList(HSQUIRRELVM vm);
 #endif /* DOXYGEN_API */

src/script/api/script_townlist.hpp

@@ -25,20 +25,23 @@ public:
 	/**
 	 * Apply a filter when building the list.
 	 * @param filter_function The function which will be doing the filtering.
-	 * @param params The params to give to the filters (minus the first param,
+	 * @param ... The params to give to the filters (minus the first param,
 	 *  which is always the index-value).
 	 * @note You can write your own filters and use them. Just remember that
 	 *  the first parameter should be the index-value, and it should return
 	 *  a bool.
 	 * @note Example:
-	 *  ScriptTownList(ScriptTown.IsActionAvailable, ScriptTown.TOWN_ACTION_BRIBE);
+	 * @code
+	 *  local bribeable_towns = ScriptTownList(ScriptTown.IsActionAvailable, ScriptTown.TOWN_ACTION_BRIBE);
+	 *
 	 *  function MinPopulation(town_id, pop)
 	 *  {
 	 *    return ScriptTown.GetPopulation(town_id) >= pop;
 	 *  }
-	 *  ScriptTownList(MinPopulation, 1000);
+	 *  local proper_towns = ScriptTownList(MinPopulation, 1000);
+	 * @endcode
 	 */
-	ScriptTownList(void *filter_function, int params, ...);
+	ScriptTownList(function filter_function, ...);
 #else
 	ScriptTownList(HSQUIRRELVM vm);
 #endif /* DOXYGEN_API */

src/script/api/script_vehiclelist.hpp

@@ -26,20 +26,23 @@ public:
 	/**
 	 * Apply a filter when building the list.
 	 * @param filter_function The function which will be doing the filtering.
-	 * @param params The params to give to the filters (minus the first param,
+	 * @param ... The params to give to the filters (minus the first param,
 	 *  which is always the index-value).
 	 * @note You can write your own filters and use them. Just remember that
 	 *  the first parameter should be the index-value, and it should return
 	 *  a bool.
 	 * @note Example:
-	 *  ScriptVehicleList(ScriptVehicle.IsInDepot);
+	 * @code
+	 *  local vehs_in_depot = ScriptVehicleList(ScriptVehicle.IsInDepot);
+	 *
 	 *  function IsType(vehicle_id, type)
 	 *  {
 	 *    return ScriptVehicle.GetVehicleType(vehicle_id) == type;
 	 *  }
-	 *  ScriptVehicleList(IsType, ScriptVehicle.VT_ROAD);
+	 *  local road_vehs = ScriptVehicleList(IsType, ScriptVehicle.VT_ROAD);
+	 * @endcode
 	 */
-	ScriptVehicleList(void *filter_function, int params, ...);
+	ScriptVehicleList(function filter_function, ...);
 #else
 	/**
 	 * The constructor wrapper from Squirrel.