(svn r23374) -Add: Doxygen files for the NoAI API (Yexo)

5 files changed, 1086 insertions, 0 deletions

diff --git a/src/script/api/Doxyfile_AI b/src/script/api/Doxyfile_AI
new file mode 100644
index 000000000..04c56db3a
--- /dev/null
+++ b/src/script/api/Doxyfile_AI
@@ -0,0 +1,250 @@
+# $Id$
+
+# This file is part of OpenTTD.
+# OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
+# OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
+
+# Doxyfile 1.5.4
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "OpenTTD NoAI API"
+PROJECT_NUMBER         =
+OUTPUT_DIRECTORY       = ../../../docs/aidocs/
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = "The $name class " \
+                         "The $name widget " \
+                         "The $name file " \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = ./
+STRIP_FROM_INC_PATH    =
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 2
+ALIASES                =
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+DISTRIBUTE_GROUP_DOC   = NO
+SUBGROUPING            = YES
+TYPEDEF_HIDES_STRUCT   = NO
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = YES
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = YES
+INTERNAL_DOCS          = YES
+CASE_SENSE_NAMES       = YES
+HIDE_SCOPE_NAMES       = NO
+SHOW_INCLUDE_FILES     = NO
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_BY_SCOPE_NAME     = NO
+GENERATE_TODOLIST      = NO
+GENERATE_TESTLIST      = NO
+GENERATE_BUGLIST       = NO
+GENERATE_DEPRECATEDLIST= NO
+ENABLED_SECTIONS       =
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = NO
+SHOW_DIRECTORIES       = NO
+FILE_VERSION_FILTER    =
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = YES
+WARN_FORMAT            = "$file:$line: $text "
+WARN_LOGFILE           =
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  = .
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = script_*.hpp \
+                         ai_*.hpp
+RECURSIVE              = YES
+EXCLUDE                =
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       =
+EXCLUDE_SYMBOLS        = GetClassName DECLARE_ENUM_AS_BIT_SET DECLARE_POSTFIX_INCREMENT
+EXAMPLE_PATH           =
+EXAMPLE_PATTERNS       = *
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             =
+INPUT_FILTER           = "./doxygen_filter.sh AI"
+FILTER_PATTERNS        =
+FILTER_SOURCE_FILES    = NO
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = NO
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = NO
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = NO
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          =
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            =
+HTML_FOOTER            =
+HTML_STYLESHEET        =
+HTML_ALIGN_MEMBERS     = YES
+GENERATE_HTMLHELP      = NO
+HTML_DYNAMIC_SECTIONS  = NO
+CHM_FILE               =
+HHC_LOCATION           =
+GENERATE_CHI           = NO
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 1
+GENERATE_TREEVIEW      = NO
+TREEVIEW_WIDTH         = 250
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         =
+LATEX_HEADER           =
+PDF_HYPERLINKS         = NO
+USE_PDFLATEX           = NO
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    =
+RTF_EXTENSIONS_FILE    =
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = NO
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_SCHEMA             =
+XML_DTD                =
+XML_PROGRAMLISTING     = YES
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           =
+INCLUDE_FILE_PATTERNS  =
+PREDEFINED             = DOXYGEN_API
+EXPAND_AS_DEFINED      = DEF_COMMAND
+SKIP_FUNCTION_MACROS   = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references
+#---------------------------------------------------------------------------
+TAGFILES               =
+GENERATE_TAGFILE       = openttd_noai.tag
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = YES
+MSCGEN_PATH            =
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = NO
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+DOT_PATH               =
+DOTFILE_DIRS           =
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 1000
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = NO
+DOT_CLEANUP            = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine
+#---------------------------------------------------------------------------
+SEARCHENGINE           = NO
diff --git a/src/script/api/ai_changelog.hpp b/src/script/api/ai_changelog.hpp
new file mode 100644
index 000000000..99d892497
--- /dev/null
+++ b/src/script/api/ai_changelog.hpp
@@ -0,0 +1,277 @@
+/* $Id$ */
+
+/*
+ * This file is part of OpenTTD.
+ * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
+ * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/**
+ * @file ai_changelog.hpp Lists all changes / additions to the API.
+ *
+ * Only new / renamed / deleted api functions will be listed here. A list of
+ * bug fixes can be found in the normal changelog. Note that removed API
+ * functions may still be available if you return an older API version
+ * in GetAPIVersion() in info.nut.
+ *
+ * \b 1.2.0
+ *
+ * 1.2.0 is not yet released. The following changes are not set in stone yet.
+ *
+ * API additions:
+ *
+ * \li AICargo::CT_AUTO_REFIT
+ * \li AICargo::CT_NO_REFIT
+ * \li AICargo::IsValidTownEffect
+ * \li AICargoList_StationAccepting
+ * \li AICompany::GetQuarterlyIncome
+ * \li AICompany::GetQuarterlyExpenses
+ * \li AICompany::GetQuarterlyCargoDelivered
+ * \li AICompany::GetQuarterlyPerformanceRating
+ * \li AICompany::GetQuarterlyCompanyValue
+ * \li AIController::GetOpsTillSuspend
+ * \li AIInfo::CONFIG_DEVELOPER
+ * \li AIOrder::GetOrderRefit
+ * \li AIOrder::IsRefitOrder
+ * \li AIOrder::SetOrderRefit
+ * \li AITown::GetCargoGoal
+ * \li AITown::GetGrowthRate
+ * \li AITown::GetLastMonthReceived
+ * \li AITown::GetTownAuthority
+ * \li AITownEffectList (to walk over all available town effects)
+ * \li AIVehicle::ERR_VEHICLE_TOO_LONG in case vehicle length limit is reached
+ *
+ * API renames:
+ * \li AITown::GetLastMonthTransported to AITown::GetLastMonthSupplied to better
+ *     reflect what it does.
+ * \li AIInfo has all its configure settings renamed from AICONFIG to just CONFIG
+ *     like CONFIG_RANDOM.
+ *
+ * API removals:
+ * \li AICompany::GetCompanyValue, use AICompany::GetQuarterlyCompanyValue instead.
+ *
+ * Other changes:
+ * \li AITown::GetLastMonthProduction no longer has prerequisites based on town
+ *     effects.
+ * \li AITown::GetLastMonthTransported no longer has prerequisites based on
+ *     town effects.
+ * \li AITown::GetLastMonthTransportedPercentage no longer has prerequisites
+ *     based on town effects.
+ *
+ * \b 1.1.2
+ *
+ * No changes
+ *
+ * \b 1.1.1
+ *
+ * No changes
+ *
+ * \b 1.1.0
+ *
+ * API additions:
+ * \li IsEnd for all lists.
+ * \li AIEventTownFounded
+ * \li AIIndustry::GetIndustryID
+ * \li AIIndustryType::INDUSTRYTYPE_TOWN
+ * \li AIIndustryType::INDUSTRYTYPE_UNKNOWN
+ * \li AIOrder::IsVoidOrder
+ * \li AIRail::GetName
+ * \li AITown::IsCity
+ *
+ * API removals:
+ * \li HasNext for all lists.
+ * \li AIAbstractList, use AIList instead.
+ * \li AIList::ChangeItem, use AIList::SetValue instead.
+ * \li AIRail::ERR_NONUNIFORM_STATIONS_DISABLED, that error is never returned anymore.
+ *
+ * Other changes:
+ * \li AIEngine::GetMaxTractiveEffort can be used for road vehicles.
+ * \li AIEngine::GetPower can be used for road vehicles.
+ * \li AIEngine::GetWeight can be used for road vehicles.
+ * \li AIIndustry::IsCargoAccepted now returns CargoAcceptState instead of a boolean.
+ * \li AIOrder::GetOrderFlags returns AIOrder::AIOF_INVALID for void orders as well.
+ * \li AIRoad::BuildDriveThroughRoadStation now allows overbuilding.
+ * \li AIRoad::BuildRoadStation now allows overbuilding.
+ *
+ * \b 1.0.5
+ *
+ * No changes
+ *
+ * \b 1.0.4
+ *
+ * No changes
+ *
+ * \b 1.0.3
+ *
+ * API additions:
+ * \li AIRail::ERR_RAILTYPE_DISALLOWS_CROSSING
+ *
+ * \b 1.0.2
+ *
+ * Other changes:
+ * \li AIBridge::GetPrice now returns the price of the bridge without the cost for the rail or road.
+ *
+ * \b 1.0.1
+ *
+ * API additions:
+ * \li AIRail::GetMaxSpeed
+ *
+ * \b 1.0.0
+ *
+ * API additions:
+ * \li AIBaseStation
+ * \li AIEngine::IsBuildable
+ * \li AIEventCompanyAskMerger
+ * \li AIIndustry::GetLastMonthTransportedPercentage
+ * \li AIInfo::AICONFIG_INGAME
+ * \li AIMarine::GetBuildCost
+ * \li AIOrder::AIOF_GOTO_NEAREST_DEPOT
+ * \li AIOrder::GetStopLocation
+ * \li AIOrder::SetStopLocation
+ * \li AIRail::RemoveRailStationTileRectangle
+ * \li AIRail::RemoveRailWaypointTileRectangle
+ * \li AIRail::GetBuildCost
+ * \li AIRoad::GetBuildCost
+ * \li AISubsidy::SubsidyParticipantType
+ * \li AISubsidy::GetSourceType
+ * \li AISubsidy::GetSourceIndex
+ * \li AISubsidy::GetDestinationType
+ * \li AISubsidy::GetDestinationIndex
+ * \li AITile::GetBuildCost
+ * \li AITown::GetLastMonthTransportedPercentage
+ * \li AIVehicleList_Depot
+ * \li AIWaypoint::WaypointType
+ * \li AIWaypoint::HasWaypointType
+ * \li Some error messages to AIWaypoint
+ *
+ * API removals:
+ * \li AIOrder::ChangeOrder, use AIOrder::SetOrderFlags instead
+ * \li AIRail::RemoveRailStationTileRect, use AIRail::RemoveRailStationTileRectangle instead
+ * \li AIRail::RemoveRailWaypoint, use AIRail::RemoveRailWaypointTileRectangle instead
+ * \li AISign::GetMaxSignID, use AISignList instead
+ * \li AIStation::ERR_STATION_TOO_LARGE, use AIError::ERR_STATION_TOO_SPREAD_OUT instead
+ * \li AISubsidy::SourceIsTown, use AISubsidy::GetSourceType instead
+ * \li AISubsidy::GetSource, use AISubsidy::GetSourceIndex instead
+ * \li AISubsidy::DestinationIsTown, use AISubsidy::GetDestinationType instead
+ * \li AISubsidy::GetDestination, use AISubsidy::GetDestinationIndex instead
+ * \li AITile::GetHeight, use AITile::GetMinHeight/GetMaxHeight/GetCornerHeight instead
+ * \li AITown::GetMaxProduction, use AITown::GetLastMonthProduction instead
+ * \li AIVehicle::SkipToVehicleOrder, use AIOrder::SkipToOrder instead
+ * \li AIWaypoint::WAYPOINT_INVALID, use AIBaseStation::STATION_INVALID instead
+ *
+ * Other changes:
+ * \li The GetName / SetName / GetLocation functions were moved from AIStation
+ *     and AIWaypoint to AIBaseStation, but you can still use AIStation.GetName
+ *     as before
+ * \li The GetConstructionDate function was moved from AIStation to
+ *     AIBaseStation, but can still be used as AIStation.GetConstructionDate
+ * \li WaypointID was replaced by StationID. All WaypointIDs from previous
+ *     savegames are invalid. Use STATION_INVALID instead of WAYPOINT_INVALID
+ * \li AIWaypointList constructor now needs a WaypointType similiar to AIStationList,
+ *     it can also handle buoys.
+ * \li AIVehicleList_Station now also works for waypoints
+ * \li Stations can be build over rail without signals that is in the right
+ *     direction for the to-be built station. It will also convert the rail if
+ *     the station's rail type supports the old type.
+ * \li GetAPIVersion() was added as function to info.nut. If it does not exist
+ *     API version 0.7 is assumed. This function should return the major and
+ *     minor number of the stable version of the API the AI is written against.
+ *     For 0.7.2 that would be 0.7, for 1.1.3 it would be 1.1, etc.
+ * \li The subsidy logic has changed. Subsidy is now awarded when cargo
+ *     originating from subsidy source is delivered to station that has subsidy
+ *     destination it its catchment area. One industry tile or one town house
+ *     is enough as long as station accepts the cargo. Awarded subsidies are no
+ *     longer bound to stations used for first delivery, any station can be
+ *     used for loading and unloading as long as cargo is transfered from
+ *     source to destination.
+ * \li Make AIEngine:CanRefitCargo() not report refittability to mail by
+ *     default for aircraft. It is not necessarily true. This means that even
+ *     if the aircraft can carry mail (as secondary cargo) it does not return
+ *     true if the aircraft cannot carry it as its only cargo.
+ * \li Improve behaviour of AIEngine::GetCargoType(), AIEventEnginePreview::GetCargoType()
+ *     and AIEngine::CanRefitCargo() for articulated vehicles. For
+ *     CanRefitCargo true is returned if at least one part can be refitted.
+ *     For GetCargoType the first most used cargo type is returned.
+ * \li AIIndustryType::GetConstructionCost() now returns -1 if the industry is
+ *     neither buildable nor prospectable.
+ * \li AIEngine::IsValidEngine will now return true if you have at least one
+ *     vehicle of that type in your company, regardless if it's still buildable
+ *     or not. AIEngine::IsBuildable returns only true when you can actually
+ *     build an engine.
+ * \li AITile::GetCargoProduction will now return the number of producers,
+ *     including houses instead the number of producing tiles. This means that
+ *     also industries that do not have a tile within the radius, but where
+ *     the search bounding box and the industry's bounding box intersect, are
+ *     counted. Previously these industries (and their cargos), although they
+ *     produced cargo for a station at the given location, were not returned.
+ * \li AIRail::BuildRail will now fail completely if there is an obstacle
+ *     between the begin and end, instead of building up to the obstacle and
+ *     returning that everything went okay.
+ * \li Orders for buoys are now waypoint orders, i.e. instead of using the
+ *     station orders for buoys one has to use waypoint orders.
+ * \li Autoreplaces can now also be set for the default group via AIGroup.
+ *
+ * \b 0.7.5
+ *
+ * No changes
+ *
+ * \b 0.7.4
+ *
+ * No changes
+ *
+ * \b 0.7.3
+ *
+ * API additions:
+ * \li AIAbstractList::SORT_ASCENDING
+ * \li AIAbstractList::SORT_DESCENDING
+ * \li AIAirport::IsAirportInformationAvailable
+ * \li AICompany::GetPresidentGender
+ * \li AICompany::SetPresidentGender
+ * \li AIEngine::GetDesignDate
+ * \li AIStation::GetConstructionDate
+ *
+ * Other changes:
+ * \li AIs are now killed when they execute a DoCommand or Sleep at a time
+ *     they are not allowed to do so.
+ * \li When the API requests a string as parameter you can give every squirrel
+ *     type and it will be converted to a string
+ * \li AIs can create subclasses of API classes and use API constants as part
+ *     of their own constants
+ *
+ * \b 0.7.2
+ *
+ * API additions:
+ * \li AIVehicle::GetReliability
+ *
+ * Other changes:
+ * \li DoCommands and sleeps in call, acall, pcall and valuators are disallowed
+ *
+ * \b 0.7.1
+ *
+ * API additions:
+ * \li AIAirport::GetPrice
+ * \li AIController::GetVersion
+ * \li AIOrder::AIOF_DEPOT_FLAGS
+ * \li AIOrder::AIOF_STOP_IN_DEPOT
+ * \li AIOrder::IsCurrentOrderPartOfOrderList
+ * \li AIOrder::IsGotoDepotOrder
+ * \li AIOrder::IsGotoStationOrder
+ * \li AIOrder::IsGotoWaypointOrder
+ * \li AISignList
+ * \li AITile::CORNER_[WSEN]
+ * \li AITile::ERR_AREA_ALREADY_FLAT
+ * \li AITile::ERR_EXCAVATION_WOULD_DAMAGE
+ * \li AITile::GetCornerHeight
+ * \li AITile::GetMaxHeight
+ * \li AITile::GetMinHeight
+ * \li AIVehicle::SendVehicleToDepotForServicing
+ *
+ * Other changes:
+ * \li GetURL() was added as optional function to info.nut
+ * \li UseAsRandomAI() was added as optional function to info.nut
+ * \li A limit was introduced on the time the AI spends in the constructor and Load function
+ *
+ * \b 0.7.0
+ * \li First stable release with the NoAI framework.
+ */
diff --git a/src/script/api/doxygen_filter.awk b/src/script/api/doxygen_filter.awk
new file mode 100644
index 000000000..e15c8da39
--- /dev/null
+++ b/src/script/api/doxygen_filter.awk
@@ -0,0 +1,285 @@
+# $Id$
+
+# This file is part of OpenTTD.
+# OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
+# OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
+
+#
+# Awk script to automatically generate the code needed
+# to export the script APIs to Squirrel.
+#
+# Note that arrays are 1 based...
+#
+
+
+BEGIN {
+	cls = ""
+	api_selected = ""
+	cls_in_api = ""
+	cls_level = 0
+	skip_function_body = "false"
+	skip_function_par = 0
+	RS = "\r|\n"
+}
+
+{
+	gsub(/Script/, api)
+}
+
+{
+	if (skip_function_body == "true") {
+		input = $0
+		gsub(/[^{]/, "", input)
+		skip_function_par += length(input)
+		if (skip_function_par > 0) {
+			input = $0
+			gsub(/[^}]/, "", input)
+			skip_function_par -= length(input)
+			if (skip_function_par == 0) skip_function_body = "false"
+		}
+	}
+	if (skip_function_body == "true") next
+}
+
+/@file/ {
+	gsub(/script/, tolower(api))
+}
+
+/^([	 ]*)\* @api/ {
+	if (api == "Script") {
+		api_selected = "true"
+		next
+	}
+
+	# By default, classes are not selected
+	if (cls_level == 0) api_selected = "false"
+
+	gsub("^([	 ]*)", "", $0)
+	gsub("* @api ", "", $0)
+
+	if ($0 == "none") {
+		api_selected = "false"
+	} else if ($0 == "-all") {
+		api_selected = "false"
+	} else if (match($0, "-" tolower(api))) {
+		api_selected = "false"
+	} else if (match($0, tolower(api))) {
+		api_selected = "true"
+	}
+
+	next
+}
+
+# Ignore forward declarations of classes
+/^(	*)class(.*);/ { next; }
+# We only want to have public functions exported for now
+/^(	*)class/     {
+	if (cls_level == 0) {
+		if (api_selected == "") {
+			print "Class '"$2"' has no @api. It won't be published to any API." > "/dev/stderr"
+			api_selected = "false"
+		}
+		public = "false"
+		cls_param[0] = ""
+		cls_param[1] = 1
+		cls_param[2] = "x"
+		cls_in_api = api_selected
+		api_selected = ""
+		cls = $2
+
+		if (cls_in_api == "true") {
+			print comment_buffer
+			print
+			print "public:"
+			comment_buffer = ""
+		}
+	} else if (cls_level == 1) {
+		if (api_selected == "") api_selected = cls_in_api
+
+		if (api_selected == "true") {
+			print comment_buffer
+			print
+			print "public:"
+			comment_buffer = ""
+		}
+		api_selected = ""
+	} else {
+		print "Classes nested too deep" > "/dev/stderr"
+		exit 1
+	}
+	cls_level++
+	next
+}
+/^(	*)public/    { if (cls_level == 1) comment_buffer = ""; public = "true";  next; }
+/^(	*)protected/ { if (cls_level == 1) comment_buffer = ""; public = "false"; next; }
+/^(	*)private/   { if (cls_level == 1) comment_buffer = ""; public = "false"; next; }
+
+# Ignore special doxygen blocks
+/^#ifndef DOXYGEN_API/          { doxygen_skip = "next"; next; }
+/^#ifdef DOXYGEN_API/           { doxygen_skip = "true"; next; }
+/^#endif \/\* DOXYGEN_API \*\// { doxygen_skip = "false"; next; }
+/^#else/                         {
+	if (doxygen_skip == "next") {
+		doxygen_skip = "true";
+	} else {
+		doxygen_skip = "false";
+	}
+	next;
+}
+{ if (doxygen_skip == "true") next }
+
+/^#/ {
+	next
+}
+
+# Store comments
+/\/\*\*.*\*\//   { comment_buffer = $0; comment = "false"; next; }
+/\/\*.*\*\//     { comment_buffer = ""; comment = "false"; next; }
+/\/\*\*/         { comment_buffer = $0 "\n"; comment = "true";  next; }
+/\/\*/           { comment_buffer = ""; comment = "false";  next; }
+/\*\//           { comment_buffer = comment_buffer $0; comment = "false"; next; }
+{
+	if (comment == "true" && !match($0, /@api/))
+	{
+		comment_buffer = comment_buffer $0 "\n"; next;
+	}
+}
+
+
+# We need to make specialized conversions for structs
+/^(	*)struct/ {
+	comments_so_far = comment_buffer
+	comment_buffer = ""
+	cls_level++
+
+	# Check if we want to publish this struct
+	if (api_selected == "") api_selected = cls_in_api
+	if (api_selected == "false") {
+		api_selected = ""
+		next
+	}
+	api_selected = ""
+
+	if (public == "false") next
+
+	print comments_so_far
+	print $0
+
+	next
+}
+
+# We need to make specialized conversions for enums
+/^(	*)enum/ {
+	comments_so_far = comment_buffer
+	comment_buffer = ""
+	cls_level++
+
+	# Check if we want to publish this enum
+	if (api_selected == "") api_selected = cls_in_api
+	if (api_selected == "false") {
+		api_selected = ""
+		next
+	}
+	api_selected = ""
+
+	if (public == "false") next
+
+	in_enum = "true"
+
+	print comments_so_far
+	print $0
+
+	next
+}
+
+# Maybe the end of the class, if so we can start with the Squirrel export pretty soon
+/};/ {
+	comment_buffer = ""
+	cls_level--
+	if (cls_level != 0) {
+		if (in_enum == "true") print
+		in_enum = "false"
+		next
+	}
+	if (cls == "") {
+		next
+	}
+	if (cls_in_api == "true") print
+	next;
+}
+
+# Empty/white lines
+/^([ 	]*)$/ {
+	print $0
+
+	next
+}
+
+# Skip non-public functions
+{ if (public == "false") next }
+
+# Add enums
+{
+	if (in_enum == "true") {
+		print comment_buffer
+		comment_buffer = ""
+		print $0
+
+		# Check if this a special error enum
+		if (match(enums[enum_size], ".*::ErrorMessages") != 0) {
+			# syntax:
+			# enum ErrorMessages {
+			#	ERR_SOME_ERROR,	// [STR_ITEM1, STR_ITEM2, ...]
+			# }
+
+			##TODO: don't print the STR_*
+		}
+		next
+	}
+}
+
+# Add a const (non-enum) value
+/^[ 	]*static const \w+ \w+ = -?\(?\w*\)?\w+;/ {
+	if (api_selected == "") api_selected = cls_in_api
+	if (api_selected == "false") {
+		api_selected = ""
+		comment_buffer = ""
+		next
+	}
+	print comment_buffer
+	print $0
+	comment_buffer = ""
+	next
+}
+
+# Add a method to the list
+/^.*\(.*\).*$/ {
+	if (cls_level != 1) next
+	if (!match($0, ";")) {
+		gsub(/ :$/, ";")
+		skip_function_body = "true"
+	}
+	if (match($0, "~")) {
+		if (api_selected != "") {
+			print "Destructor for '"cls"' has @api. Tag ignored." > "/dev/stderr"
+			api_selected = ""
+		}
+		next
+	}
+
+	# Check if we want to publish this function
+	if (api_selected == "") api_selected = cls_in_api
+	if (api_selected == "false") {
+		api_selected = ""
+		comment_buffer = ""
+		next
+	}
+	api_selected = ""
+
+	print comment_buffer
+	print $0
+	comment_buffer = ""
+
+	next
+}
diff --git a/src/script/api/doxygen_filter.sh b/src/script/api/doxygen_filter.sh
new file mode 100644
index 000000000..fd8fca98b
--- /dev/null
+++ b/src/script/api/doxygen_filter.sh
@@ -0,0 +1,27 @@
+#!/bin/bash
+
+# $Id$
+
+# This file is part of OpenTTD.
+# OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
+# OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
+
+# Set neutral locale so sort behaves the same everywhere
+LC_ALL=C
+export LC_ALL
+
+# We really need gawk for this!
+AWK=gawk
+
+${AWK} --version > /dev/null 2> /dev/null
+if [ "$?" != "0" ]; then
+	echo "This script needs gawk to run properly"
+	exit 1
+fi
+
+case $2 in
+	*ai_changelog.hpp) cat $2; exit 0;;
+esac
+
+${AWK} -v api=$1 -f doxygen_filter.awk $2
diff --git a/src/script/api/script_info_docs.hpp b/src/script/api/script_info_docs.hpp
new file mode 100644
index 000000000..28f2b53f0
--- /dev/null
+++ b/src/script/api/script_info_docs.hpp
@@ -0,0 +1,247 @@
+/* $Id$ */
+
+/*
+ * This file is part of OpenTTD.
+ * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
+ * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/** @file script_info_docs.hpp Description of the functions an Script can/must provide in ScriptInfo. */
+
+/* This file exists purely for doxygen purposes. */
+
+/**
+ * 'Abstract' class of the Scripts use to register themselves.
+ *
+ * @note This class is not part of the API. It is purely to document what
+ *       Scripts must or can implemented to provide information to OpenTTD to
+ *       base configuring/starting/loading the Script on.
+ *
+ * @note The required functions are also needed for Script Libraries. As such
+ *       the information here can be used for libraries, but the information
+ *       will not be shown in the GUI except for error/debug messages.
+ *
+ * @api ai
+ */
+class ScriptInfo {
+public:
+	/**
+	 * Gets the author name to be shown in the 'Available Scripts' window.
+	 *
+	 * @return The author name of the Script.
+	 * @note This function is required.
+	 */
+	string GetAuthor();
+
+	/**
+	 * Gets the Scripts name. This is shown in the 'Available Scripts' window
+	 * and at all other places where the Script is mentioned, like the debug
+	 * window or OpenTTD's help message. The name is used to uniquely
+	 * identify an Script within OpenTTD and this name is used in savegames
+	 * and the configuration file.
+	 *
+	 * @return The name of the Script.
+	 * @note This function is required.
+	 */
+	string GetName();
+
+	/**
+	 * Gets a 4 ASCII character short name of the Script to uniquely
+	 * identify it from other Scripts. The short name is primarily
+	 * used as unique identifier for the content system.
+	 * The content system uses besides the short name also the
+	 * MD5 checksum of all the source files to uniquely identify
+	 * a specific version of the Script.
+	 *
+	 * The short name must consist of precisely four ASCII
+	 * characters, or more precisely four non-zero bytes.
+	 *
+	 * @return The name of the Script.
+	 * @note This function is required.
+	 */
+	string GetShortName();
+
+	/**
+	 * Gets the description to be shown in the 'Available Scripts' window.
+	 *
+	 * @return The description for the Script.
+	 * @note This function is required.
+	 */
+	string GetDescription();
+
+	/**
+	 * Gets the version of the Script. This is a number to (in theory)
+	 * uniquely identify the versions of an Script. Generally the
+	 * 'instance' of an Script with the highest version is chosen to
+	 * be loaded.
+	 *
+	 * When OpenTTD finds, during starting, a duplicate Script with the
+	 * same version number one is randomly chosen. So it is
+	 * important that this number is regularly updated/incremented.
+	 *
+	 * @return The version number of the Script.
+	 * @note This function is required.
+	 */
+	int GetVersion();
+
+	/**
+	 * Gets the lowest version of the Script that OpenTTD can still load
+	 * the savegame of. In other words, from which version until this
+	 * version can the Script load the savegames.
+	 *
+	 * If this function does not exist OpenTTD assumes it can only
+	 * load savegames of this version. As such it will not upgrade
+	 * to this version upon load.
+	 *
+	 * @return The lowest version number we load the savegame data.
+	 * @note This function is optional.
+	 */
+	int MinVersionToLoad();
+
+	/**
+	 * Gets the development/release date of the Script.
+	 *
+	 * The intention of this is to give the user an idea how old the
+	 * Script is and whether there might be a newer version.
+	 *
+	 * @return The development/release date for the Script.
+	 * @note This function is required.
+	 */
+	string GetDate();
+
+	/**
+	 * Can this Script be used as random Script?
+	 *
+	 * The idea behind this function is to 'forbid' highly
+	 * competitive or other special Scripts from running in games unless
+	 * the user explicitly selects the Script to be loaded. This to
+	 * try to prevent users from complaining that the Script is too
+	 * aggressive or does not build profitable routes.
+	 *
+	 * If this function does not exist OpenTTD assumes the Script can
+	 * be used as random Script. As such it will be randomly chosen.
+	 *
+	 * @return True if the Script can be used as random Script.
+	 * @note This function is optional.
+	 *
+	 * @api -game
+	 */
+	bool UseAsRandomAI();
+
+	/**
+	 * Gets the name of main class of the Script so OpenTTD knows
+	 * what class to instantiate.
+	 *
+	 * @return The class name of the Script.
+	 * @note This function is required.
+	 */
+	string CreateInstance();
+
+	/**
+	 * Gets the API version this Script is written for. If this function
+	 * does not exist API compatability with version 0.7 is assumed.
+	 * If the function returns something OpenTTD does not understand,
+	 * for example a newer version or a string that is not a version,
+	 * the Script will not be loaded.
+	 *
+	 * Although in the future we might need to make a separate
+	 * compatability 'wrapper' for a specific version of OpenTTD, for
+	 * example '0.7.1', we will use only the major and minor number
+	 * and not the bugfix number as valid return for this function.
+	 *
+	 * Valid return values are:
+	 * - "0.7"
+	 * - "1.0"
+	 * - "1.1"
+	 * - "1.2"
+	 *
+	 * @return The version this Script is compatible with.
+	 * @note This function is optional.
+	 */
+	string GetAPIVersion();
+
+	/**
+	 * Gets the URL to be shown in the 'this Script has crashed' message
+	 * and in the 'Available Scripts' window. If this function does not
+	 * exist no URL will be shown.
+	 *
+	 * This function purely exists to redirect users of the Script to the
+	 * right place on the internet to discuss the Script and report bugs
+	 * of this Script.
+	 *
+	 * @return The URL to show.
+	 * @note This function is optional.
+	 */
+	string GetURL();
+
+	/**
+	 * Gets the settings that OpenTTD shows in the "Script Parameters" window
+	 * so the user can customize the Script. This is a special function that
+	 * doesn't need to return anything. Instead you can call AddSetting
+	 * and AddLabels here.
+	 *
+	 * @note This function is optional.
+	 */
+	void GetSettings();
+
+	/** Miscellaneous flags for Script settings. */
+	enum ScriptConfigFlags {
+		CONFIG_NONE,      ///< Normal setting.
+		CONFIG_RANDOM,    ///< When randomizing the Script, pick any value between min_value and max_value.
+		CONFIG_BOOLEAN,   ///< This value is a boolean (either 0 (false) or 1 (true) ).
+		CONFIG_INGAME,    ///< This setting can be changed while the Script is running.
+		CONFIG_DEVELOPER, ///< This setting will only be visible when the Script development tools are active.
+	};
+
+	/**
+	 * Add a user configurable setting for this Script. You can call this
+	 * as many times as you have settings.
+	 * @param setting_description A table with all information about a
+	 *  single setting. The table should have the following name/value pairs:
+	 *  - name The name of the setting, this is used in openttd.cfg to
+	 *    store the current configuration of Scripts. Required.
+	 *  - description A single line describing the setting. Required.
+	 *  - min_value The minimum value of this setting. Required for integer
+	 *    settings and not allowed for boolean settings.
+	 *  - max_value The maximum value of this setting. Required for integer
+	 *    settings and not allowed for boolean settings.
+	 *  - easy_value The default value if the easy difficulty level
+	 *    is selected. Required.
+	 *  - medium_value The default value if the medium difficulty level
+	 *    is selected. Required.
+	 *  - hard_value The default value if the hard difficulty level
+	 *    is selected. Required.
+	 *  - custom_value The default value if the custom difficulty level
+	 *    is selected. Required.
+	 *  - random_deviation If this property has a nonzero value, then the
+	 *    actual value of the setting in game will be
+	 *    user_configured_value + random(-random_deviation, random_deviation).
+	 *    Not allowed if the CONFIG_RANDOM flag is set, otherwise optional.
+	 *  - step_size The increase/decrease of the value every time the user
+	 *    clicks one of the up/down arrow buttons. Optional, default is 1.
+	 *  - flags Bitmask of some flags, see ScriptConfigFlags. Required.
+	 *
+	 * @note This is a function provided by OpenTTD, you don't have to
+	 * include it in your Script but should just call it from GetSettings.
+	 */
+	void AddSetting(table setting_description);
+
+	/**
+	 * Add labels for the values of a setting. Instead of a number the
+	 *  user will see the corresponding name.
+	 * @param setting_name The name of the setting.
+	 * @param value_names A table that maps values to names. The first
+	 *   character of every identifier is ignored and the rest should
+	 *   be the an integer of the value you define a name for. The value
+	 *   is a short description of that value.
+	 * To define labels for a setting named "competition_level" you could
+	 * for example call it like this:
+	 * AddLabels("competition_level", {_0 = "no competition", _1 = "some competition",
+	 * _2 = "a lot of competition"});
+	 *
+	 * @note This is a function provided by OpenTTD, you don't have to
+	 * include it in your Script but should just call it from GetSettings.
+	 */
+	void AddLabels(const char *setting_name, table value_names);
+};