Index: src/script/api/script_controller.hpp
===================================================================
--- src/script/api/script_controller.hpp        (revision 27110)
+++ src/script/api/script_controller.hpp        (working copy)
@@ -18,8 +18,26 @@
 
 /**
  * The Controller, the class each Script should extend. It creates the Script,
- *  makes sure the logic kicks in correctly, and that GetTick() has a valid
+ *  makes sure the logic kicks in correctly, and that #GetTick() has a valid
  *  value.
+ *
+ * When starting a new game, or when loading a game, OpenTTD tries to match a
+ *  script that matches to the specified version as close as possible. It tries
+ *  (from first to last, stopping as soon as the attempt succeeds)
+ *
+ *  - load the exact same version of the same script,
+ *  - load the latest version of the same script that supports loading data from
+ *    the saved version (the version of saved data must be equal or greater
+ *    than ScriptInfo::MinVersionToLoad),
+ *  - load the latest version of the same script (ignoring version requirements),
+ *  - (for AIs) load a random AI, and finally
+ *  - (for AIs) load the dummy AI.
+ *
+ * If a script was found, an instance is constructed of the class derived from ScriptController.
+ * If there is script data available in the loaded game, #Load is called with the data.
+ * Finally, #Start is called to start execution of the script.
+ * See also http://wiki.openttd.org/AI:Save/Load for more details.
+ *
  * @api ai game
  */
 class ScriptController {
@@ -46,7 +64,49 @@
         */
        void Start();
 
+#ifdef DOXYGEN_API
        /**
+        * Save the state of the script.
+        *
+        * By implementing this function, you can store some data inside the savegame.
+        *   The function should return a table with the information you want to store.
+        *   You can only store:
+        *
+        *   - integers,
+        *   - strings,
+        *   - arrays (max. 25 levels deep),
+        *   - tables (max. 25 levels deep),
+        *   - booleans, and
+        *   - nulls.
+        *
+        * In particular, instances of classes can't be saved including
+        *   ScriptList. Such a list should be converted to an array or table on
+        *   save and converted back on load.
+        *
+        * The function is called as soon as the user saves the game,
+        *   independently of other activities of the script. The script is not
+        *   notified of the call. To avoid race-conditions between #Save and the
+        *   other script code, change variables directly after a #Sleep, it is
+        *   very unlikely, to get interrupted at that point in the execution.
+        * See also http://wiki.openttd.org/AI:Save/Load for more details.
+        *
+        * @note No other information is saved than the table returned by #Save.
+        *   For example all pending events are lost as soon as the game is loaded.
+        *
+        * @return Data of the script that should be stored in the save game.
+        */
+       SquirrelTable Save();
+
+       /**
+        * Load saved data just before calling #Start.
+        * The function is only called when there is data to load.
+        * @param version Version number of the script that created the \a data.
+        * @param data Data that was saved (return value of #Save).
+        */
+       void Load(int version, SquirrelTable data);
+#endif /* DOXYGEN_API */
+
+       /**
         * Find at which tick your script currently is.
         * @return returns the current tick.
         */