From e436e2ef405ad1ff3a3a26856f30504582888e0e Mon Sep 17 00:00:00 2001 From: frosch Date: Sun, 24 Mar 2024 19:00:06 +0100 Subject: [PATCH] Codefix: broken links and syntax issues in script API documentation --- src/script/api/doxygen_filter.awk | 5 ++++- src/script/api/script_companymode.hpp | 4 ++-- src/script/api/script_grouplist.hpp | 8 +++++--- src/script/api/script_industrylist.hpp | 11 +++++++---- src/script/api/script_league.cpp | 4 ++-- src/script/api/script_league.hpp | 4 ++-- src/script/api/script_list.hpp | 6 ++++-- src/script/api/script_signlist.hpp | 8 +++++--- src/script/api/script_story_page.hpp | 8 ++++---- src/script/api/script_subsidylist.hpp | 8 +++++--- src/script/api/script_townlist.hpp | 11 +++++++---- src/script/api/script_vehiclelist.hpp | 11 +++++++---- 12 files changed, 54 insertions(+), 34 deletions(-) diff --git a/src/script/api/doxygen_filter.awk b/src/script/api/doxygen_filter.awk index 7e3f387a0d..d396cc66e8 100644 --- a/src/script/api/doxygen_filter.awk +++ b/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 = "" diff --git a/src/script/api/script_companymode.hpp b/src/script/api/script_companymode.hpp index 8378e11c4c..1514eefe86 100644 --- a/src/script/api/script_companymode.hpp +++ b/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(); }; diff --git a/src/script/api/script_grouplist.hpp b/src/script/api/script_grouplist.hpp index d85303b854..c4b2bb4fcc 100644 --- a/src/script/api/script_grouplist.hpp +++ b/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. diff --git a/src/script/api/script_industrylist.hpp b/src/script/api/script_industrylist.hpp index 2139b2258e..9390c19645 100644 --- a/src/script/api/script_industrylist.hpp +++ b/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. diff --git a/src/script/api/script_league.cpp b/src/script/api/script_league.cpp index 28a4e8e674..a2b6b93795 100644 --- a/src/script/api/script_league.cpp +++ b/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_counter(text); CCountedPtr 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_counter(text); diff --git a/src/script/api/script_league.hpp b/src/script/api/script_league.hpp index d57e5a484a..0cfa858c37 100644 --- a/src/script/api/script_league.hpp +++ b/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. diff --git a/src/script/api/script_list.hpp b/src/script/api/script_list.hpp index 199869ed71..0fb6d9ea6d 100644 --- a/src/script/api/script_list.hpp +++ b/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 */ }; diff --git a/src/script/api/script_signlist.hpp b/src/script/api/script_signlist.hpp index 7e5117fca0..e814b441ef 100644 --- a/src/script/api/script_signlist.hpp +++ b/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 */ diff --git a/src/script/api/script_story_page.hpp b/src/script/api/script_story_page.hpp index 4213f5afe6..a15af1dc4e 100644 --- a/src/script/api/script_story_page.hpp +++ b/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); diff --git a/src/script/api/script_subsidylist.hpp b/src/script/api/script_subsidylist.hpp index 281a6a5880..f0fa9d97d2 100644 --- a/src/script/api/script_subsidylist.hpp +++ b/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 */ diff --git a/src/script/api/script_townlist.hpp b/src/script/api/script_townlist.hpp index 8e24d8af0e..42d15d06e5 100644 --- a/src/script/api/script_townlist.hpp +++ b/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 */ diff --git a/src/script/api/script_vehiclelist.hpp b/src/script/api/script_vehiclelist.hpp index c629bc48d2..ad4b3cb0ef 100644 --- a/src/script/api/script_vehiclelist.hpp +++ b/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.