summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authortruebrain <truebrain@openttd.org>2011-11-29 23:31:55 +0000
committertruebrain <truebrain@openttd.org>2011-11-29 23:31:55 +0000
commit0f9954ec1bfa95e487fa709cb64e01deb0e3cba8 (patch)
treeced3cb6f5a9d3206086f6ec4fb92f8cc35ec1d62 /src
parent7158aaea3100fbae72c75645800592117375f897 (diff)
downloadopenttd-0f9954ec1bfa95e487fa709cb64e01deb0e3cba8.tar.xz
(svn r23374) -Add: Doxygen files for the NoAI API (Yexo)
Diffstat (limited to 'src')
-rw-r--r--src/script/api/Doxyfile_AI (renamed from src/ai/api/Doxyfile)10
-rw-r--r--src/script/api/ai_changelog.hpp (renamed from src/ai/api/ai_changelog.hpp)0
-rw-r--r--src/script/api/doxygen_filter.awk285
-rw-r--r--src/script/api/doxygen_filter.sh27
-rw-r--r--src/script/api/script_info_docs.hpp (renamed from src/ai/api/ai_info_docs.hpp)124
5 files changed, 381 insertions, 65 deletions
diff --git a/src/ai/api/Doxyfile b/src/script/api/Doxyfile_AI
index 9ce9684a3..04c56db3a 100644
--- a/src/ai/api/Doxyfile
+++ b/src/script/api/Doxyfile_AI
@@ -11,7 +11,7 @@
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING = UTF-8
-PROJECT_NAME = "OpenTTD NoAI API "
+PROJECT_NAME = "OpenTTD NoAI API"
PROJECT_NUMBER =
OUTPUT_DIRECTORY = ../../../docs/aidocs/
CREATE_SUBDIRS = NO
@@ -95,8 +95,8 @@ WARN_LOGFILE =
#---------------------------------------------------------------------------
INPUT = .
INPUT_ENCODING = UTF-8
-FILE_PATTERNS = *.h \
- *.hpp
+FILE_PATTERNS = script_*.hpp \
+ ai_*.hpp
RECURSIVE = YES
EXCLUDE =
EXCLUDE_SYMLINKS = NO
@@ -106,7 +106,7 @@ EXAMPLE_PATH =
EXAMPLE_PATTERNS = *
EXAMPLE_RECURSIVE = NO
IMAGE_PATH =
-INPUT_FILTER =
+INPUT_FILTER = "./doxygen_filter.sh AI"
FILTER_PATTERNS =
FILTER_SOURCE_FILES = NO
#---------------------------------------------------------------------------
@@ -213,7 +213,7 @@ SKIP_FUNCTION_MACROS = YES
# Configuration::additions related to external references
#---------------------------------------------------------------------------
TAGFILES =
-GENERATE_TAGFILE = openttd.tag
+GENERATE_TAGFILE = openttd_noai.tag
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
PERL_PATH = /usr/bin/perl
diff --git a/src/ai/api/ai_changelog.hpp b/src/script/api/ai_changelog.hpp
index 99d892497..99d892497 100644
--- a/src/ai/api/ai_changelog.hpp
+++ b/src/script/api/ai_changelog.hpp
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/ai/api/ai_info_docs.hpp b/src/script/api/script_info_docs.hpp
index 1f8f8b1fb..28f2b53f0 100644
--- a/src/ai/api/ai_info_docs.hpp
+++ b/src/script/api/script_info_docs.hpp
@@ -7,86 +7,88 @@
* 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_info_docs.hpp Description of the functions an AI can/must provide in AIInfo. */
+/** @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 class AIs/AI libraries use to register themselves.
+ * 'Abstract' class of the Scripts use to register themselves.
*
* @note This class is not part of the API. It is purely to document what
- * AIs must or can implemented to provide information to OpenTTD to
- * base configuring/starting/loading the AI on.
+ * 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 AI Libraries. As such
+ * @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 AIInfo {
+class ScriptInfo {
public:
/**
- * Gets the author name to be shown in the 'Available AIs' window.
+ * Gets the author name to be shown in the 'Available Scripts' window.
*
- * @return The author name of the AI.
+ * @return The author name of the Script.
* @note This function is required.
*/
string GetAuthor();
/**
- * Gets the AIs name. This is shown in the 'Available AIs' window
- * and at all other places where the AI is mentioned, like the debug
+ * 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 AI within OpenTTD and this name is used in savegames
+ * identify an Script within OpenTTD and this name is used in savegames
* and the configuration file.
*
- * @return The name of the AI.
+ * @return The name of the Script.
* @note This function is required.
*/
string GetName();
/**
- * Gets a 4 ASCII character short name of the AI to uniquely
- * identify it from other AIs. The short name is primarily
+ * 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 AI.
+ * 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 AI.
+ * @return The name of the Script.
* @note This function is required.
*/
string GetShortName();
/**
- * Gets the description to be shown in the 'Available AIs' window.
+ * Gets the description to be shown in the 'Available Scripts' window.
*
- * @return The description for the AI.
+ * @return The description for the Script.
* @note This function is required.
*/
string GetDescription();
/**
- * Gets the version of the AI. This is a number to (in theory)
- * uniquely identify the versions of an AI. Generally the
- * 'instance' of an AI with the highest version is chosen to
+ * 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 AI with the
+ * 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 AI.
+ * @return The version number of the Script.
* @note This function is required.
*/
int GetVersion();
/**
- * Gets the lowest version of the AI that OpenTTD can still load
+ * 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 AI load the savegames.
+ * 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
@@ -98,48 +100,50 @@ public:
int MinVersionToLoad();
/**
- * Gets the development/release date of the AI.
+ * Gets the development/release date of the Script.
*
* The intention of this is to give the user an idea how old the
- * AI is and whether there might be a newer version.
+ * Script is and whether there might be a newer version.
*
- * @return The development/release date for the AI.
+ * @return The development/release date for the Script.
* @note This function is required.
*/
string GetDate();
/**
- * Can this AI be used as random AI?
+ * Can this Script be used as random Script?
*
* The idea behind this function is to 'forbid' highly
- * competitive or other special AIs from running in games unless
- * the user explicitly selects the AI to be loaded. This to
- * try to prevent users from complaining that the AI is too
+ * 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 AI can
- * be used as random AI. As such it will be randomly chosen.
+ * 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 AI can be used as random AI.
+ * @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 AI so OpenTTD knows
+ * Gets the name of main class of the Script so OpenTTD knows
* what class to instantiate.
*
- * @return The class name of the AI.
+ * @return The class name of the Script.
* @note This function is required.
*/
string CreateInstance();
/**
- * Gets the API version this AI is written for. If this function
+ * 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 AI will not be loaded.
+ * 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
@@ -152,19 +156,19 @@ public:
* - "1.1"
* - "1.2"
*
- * @return The version this AI is compatible with.
+ * @return The version this Script is compatible with.
* @note This function is optional.
*/
string GetAPIVersion();
/**
- * Gets the URL to be shown in the 'this AI has crashed' message
- * and in the 'Available AIs' window. If this function does not
+ * 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 AI to the
- * right place on the internet to discuss the AI and report bugs
- * of this AI.
+ * 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.
@@ -172,8 +176,8 @@ public:
string GetURL();
/**
- * Gets the settings that OpenTTD shows in the "AI Parameters" window
- * so the user can customize the AI. This is a special function that
+ * 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.
*
@@ -181,22 +185,22 @@ public:
*/
void GetSettings();
- /** Miscellaneous flags for AI settings. */
- enum AIConfigFlags {
- AICONFIG_NONE, ///< Normal setting.
- AICONFIG_RANDOM, ///< When randomizing the AI, pick any value between min_value and max_value.
- AICONFIG_BOOLEAN, ///< This value is a boolean (either 0 (false) or 1 (true) ).
- AICONFIG_INGAME, ///< This setting can be changed while the AI is running.
- AICONFIG_AI_DEVELOPER, ///< This setting will only be visible when the ai development tools are active.
+ /** 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 AI. You can call this
+ * 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 AIs. Required.
+ * 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.
@@ -213,13 +217,13 @@ public:
* - 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 AICONFIG_RANDOM flag is set, otherwise optional.
+ * 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 AIConfigFlags. Required.
+ * - 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 AI but should just call it from GetSettings.
+ * include it in your Script but should just call it from GetSettings.
*/
void AddSetting(table setting_description);
@@ -237,7 +241,7 @@ public:
* _2 = "a lot of competition"});
*
* @note This is a function provided by OpenTTD, you don't have to
- * include it in your AI but should just call it from GetSettings.
+ * include it in your Script but should just call it from GetSettings.
*/
void AddLabels(const char *setting_name, table value_names);
};