Doxygen doc overhaul

doc/angelscript/Game2Script/script_callbacks.h

@@ -0,0 +1,39 @@
+
+namespace Game2Script {
+
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Game2Script
+ *  @{
+ */   
+
+/** Required; Script setup function - invoked once when script is loaded.
+*   If not present, the game will report error and abandon the script.
+*/
+void main();
+
+/** Optional; Script update function - invoked once every rendered frame.
+*   @param dt Elapsed time (delta time) in seconds.
+*/
+void frameStep(float dt);
+
+/** Optional; Invoked if a registered event is triggered, see Script2Game::game::registerForEvent.
+*   @param event Event code.
+*   @param param Event-specific parameter, see docs for the event codes.
+*/
+void eventCallback(Script2Game::scriptEvents event, int param);
+
+/** Optional; Invoked when a vehicle touches an eventbox which has no custom handler function.
+*   @param trigger_type Unused, always 0.
+*   @param inst Unique ID of the terrain object instance which created the eventbox.
+*   @param box Name of the eventbox as defined by the terrain object's ODEF file.
+*   @param nodeid Number of the node which triggered the event, or -1 if not known.
+*/
+void defaultEventCallback(int trigger_type, string inst, string box, int nodeid);
+
+/** @}*/   //addtogroup Game2Script
+/** @}*/   //addtogroup ScriptSideAPIs
+
+} // namespace Game2Script

doc/angelscript/BeamClass.h → doc/angelscript/Script2Game/BeamClass.h

@@ -1,3 +1,17 @@
+
+namespace Script2Game {
+
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Script2Game
+ *  @{
+ */    
+
+/**
+ * @brief Binding of RoR::Actor; a softbody-physics gameplay object, can be anything from soda can to space shuttle.
+ */
 class BeamClass
 {
 public:
@@ -179,3 +193,9 @@ class BeamClass
 	*/	
 	Ogre::Vector3 getNodePosition(int nodeNumber);
 }
+
+/// @}    //addtogroup Script2Game
+/// @}    //addtogroup ScriptSideAPIs
+
+} //namespace Script2Game
+

doc/angelscript/CVarClass.h → doc/angelscript/Script2Game/CVarClass.h

@@ -1,4 +1,14 @@
 
+namespace Script2Game {
+
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Script2Game
+ *  @{
+ */    
+
 /**
  * @brief Types and special attributes of cvars.
  * @note Default cvar type is string - To create a string cvar, enter '0' as flags.
@@ -13,7 +23,7 @@ enum CVarFlags
 };
 
 /**
- * @brief A console variable, usually defined in RoR.cfg but also created by users or scripts.
+ * @brief Binding of RoR::CVar; A console variable, usually defined in RoR.cfg but also created by users or scripts.
  */
 class CVarClass
 {
@@ -30,5 +40,10 @@ class CVarClass
 
     bool                    getBool() const  { return (bool)m_value_num; }
 
-    std::string const&      getName() const       { return m_name; }
+    std::string const&      getName() const  { return m_name; }
 };
+
+/// @}    //addtogroup Script2Game
+/// @}    //addtogroup ScriptSideAPIs
+
+} //namespace Script2Game

doc/angelscript/ConsoleClass.h → doc/angelscript/Script2Game/ConsoleClass.h

@@ -1,7 +1,16 @@
 
+namespace Script2Game {
+
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Script2Game
+ *  @{
+ */    
 
 /**
- * @brief A class that gives you access to console variables (cvars), usually defined in RoR.cfg file.
+ * @brief Binding of RoR::Console; provides console variables (cvars), usually defined in RoR.cfg file.
  * @note This object is created automatically as global variable `console`.
  */
 class ConsoleClass
@@ -33,3 +42,8 @@ class ConsoleClass
      */
     CVar* cVarGet(std::string const& input_name, int flags);
 };
+
+/// @}    //addtogroup Script2Game
+/// @}    //addtogroup ScriptSideAPIs
+
+} //namespace Script2Game

doc/angelscript/game.h → doc/angelscript/Script2Game/GameScriptClass.h

@@ -17,25 +17,22 @@ along with Rigs of Rods.  If not, see <http://www.gnu.org/licenses/>.
 */
 // created on 23th May 2011 by neorej16
 
-/*! @mainpage
+namespace Script2Game {
 
-	This is the documentation for the scripting interface of Rigs of Rods.
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
 
-	If you're wondering what arguments to pass to a function or what a function does, then this is where you should be.
-
-	If you cannot find the answer here, then search the forum for your question.
-	If that didn't provide an answer either, then ask your question in the Scripting forum:
-	http://www.rigsofrods.org/forums/167-Scripting
-
-	Please note that the documentation is work in progress.
-*/
+/** \addtogroup Script2Game
+ *  @{
+ */    
 
 /**
- * @brief A general class that will provide you with general functions
- * @note The game object is already created for you, you don't need to create it yourself.
+ * @brief Binding of RoR::GameScript; A general class that will provide you with general functions.
+ * @note Created automatically as global variable `game`.
  *       E.g.: you can log a message using game.log("Hi, I'm a message");
  */
-class game
+class GameScriptClass
 {
 public:
 	/**
@@ -460,3 +457,8 @@ class game
 	*/
 	void quitGame();
 };
+
+/// @}    //addtogroup Script2Game
+/// @}    //addtogroup ScriptSideAPIs
+
+} //namespace Script2Game

doc/angelscript/InputEngineClass.h → doc/angelscript/Script2Game/InputEngineClass.h

@@ -1,7 +1,16 @@
 
+namespace Script2Game {
+
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Script2Game
+ *  @{
+ */    
 
 /**
- * @brief Manages input devices, their configuration (input.map ...) and state.
+ * @brief Binding of RoR::InputEngine; Manages input devices, their configuration (input.map ...) and state.
  * @note This object is created automatically as global variable `inputs`.
  */
 class InputEngineClass
@@ -29,3 +38,8 @@ class InputEngineClass
     bool getEventBoolValueBounce(inputEvents ev, float time=0.2);    
 
 };
+
+/// @}    //addtogroup Script2Game
+/// @}    //addtogroup ScriptSideAPIs
+
+} //namespace Script2Game

doc/angelscript/LocalStorage.h → doc/angelscript/Script2Game/LocalStorage.h

@@ -1,5 +1,17 @@
+
+namespace Script2Game {
+
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Script2Game
+ *  @{
+ */    
+
 /**
- * @brief A class that allows your script to store data persistently.
+ * @brief Binding of LocalStorage; A class that allows your script to store data persistently.
+ *
  * The data will be stored on the hard disk of the user. The data will stay available until the user clears his cache.
  * Your data will be saved automatically if the object is destroyed or when you call the save() method.
  * To get your data, you'll have to use the correct get function, as that function will have to convert the data from a string to the correct datatype.
@@ -104,3 +116,8 @@ class LocalStorage
 	 */
 	void changeSection(const string section);
 };
+
+/// @}    //addtogroup Script2Game
+/// @}    //addtogroup ScriptSideAPIs
+
+} //namespace Script2Game

doc/angelscript/VehicleAI.h → doc/angelscript/Script2Game/VehicleAIClass.h

@@ -21,13 +21,21 @@
 */
 
 /**
-	@file   VehicleAI.h
+	@file
 	@brief  Simple waypoint AI
 	@author AnotherFoxGuy
 	@date   03/2016
 */
 
+namespace Script2Game {
 
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Script2Game
+ *  @{
+ */    
 
 /**
 *	Enum with AI events
@@ -49,8 +57,10 @@ enum Ai_values
 	AI_POWER
 };
 
-
-class VehicleAI 
+/**
+ * @brief Binding of RoR::VehicleAI; Vehicle driving AI using waypoints.
+ */
+class VehicleAIClass
 {
 public:
 	/**
@@ -91,3 +101,8 @@ class VehicleAI
 	void SetValueAtWaypoint(Ogre::String id, int value_id, float value);
 
 }
+
+/// @}    //addtogroup Script2Game
+/// @}    //addtogroup ScriptSideAPIs
+
+} //namespace ScriptSideAPIs

doc/angelscript/global_functions.h → doc/angelscript/Script2Game/globals.h

@@ -17,6 +17,16 @@ along with Rigs of Rods.  If not, see <http://www.gnu.org/licenses/>.
 */
 // created on 25th May 2011.
 
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Script2Game
+ *  @{
+ */   
+
+namespace Script2Game {
+
 /**
  * This is an alias for game.log(string message).
  * @see game.log
@@ -405,3 +415,8 @@ enum truckStates {
 	TS_RECYCLE,        //!< waiting for reusage
 	TS_DELETED,        //!< special used when truck pointer is 0
 };
+
+} // namespace Script2Game
+
+/// @}    //addtogroup Script2Game
+/// @}    //addtogroup ScriptSideAPIs

doc/angelscript/races.as → doc/angelscript/Script2Script/races.as.h

@@ -4,6 +4,16 @@
  * @author neorej16
  */
 
+namespace Script2Script { 
+
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Script2Script
+ *  @{
+ */
+
 /**
  * A function signature for the callback pointers.
  * When you need to use a RACE_EVENT_CALLBACK as parameter, then
@@ -42,7 +52,8 @@ void raceCancelPointHandler(int trigger_type, string inst, string box, int nodei
  *          raceManager races()
  *		\endcode
  */
-class racesManager {
+class racesManager
+{
 public:
 	int raceCount;			//!< the raceID+1 of the last race.
 	int currentRace;		//!< the ID of the current race. (-1 is there's no race running at the moment)
@@ -559,4 +570,55 @@ class racesManager {
 	 * @param raceID the ID of the race
 	 */
 	void loadRace(int raceID);
-}
+};
+
+/** This class manages a race (singular!)
+* You should only use this directly if the racesManager doesn't suit your needs
+*/
+class raceBuilder
+{
+	string raceName;
+	double[][][] checkpoints;
+	array<array<string>> objNames;
+	int checkPointsCount;
+	int id;
+	double bestLapTime;
+	double bestRaceTime;
+	int laps;
+	double[] bestTimeTillPoint;
+	double[] lastTimeTillPoint;
+	int finishNum;
+	int startNum;
+	int[] chpInstances; // needed to be able to remove races
+	bool locked;
+	bool completed;
+	int penaltyTime;
+	string raceVersion;
+	bool isBuilt;
+	bool awaitingRecycling;
+	bool hidden;
+	string raceBuilderVersion;    
+
+    raceBuilder(int id);
+    void setVersion(const string &in version);
+    void addChpCoordinates(double[][] checkpoints_in, const string &in objName_checkpoint, const string &in objName_start, const string &in objName_finish, uint startNumber);
+    int getNextCheckpointNum(int lastCheckpoint);
+    int getPreviousCheckpointNum(int lastCheckpoint);
+    void addCheckpoint(int number, const string &in objName, const double[] &in v);
+    void deleteCheckpoint(int number);
+    uint getRealInstanceCount(int chpNum);
+    bool checkpointExists(int chpNum, int instance);
+    void deleteCheckpoint(int number, int instance);
+    void destroy(); //!< this function removes all checkpoints again
+    void hide();
+    void unhide();
+    void setLaps(int laps_in);
+    bool isLocked();
+    void saveRace(Script2Game::LocalStorage@ d);
+    void loadRace(Script2Game::LocalStorage@ d);  
+};
+
+/** @}*/   //addtogroup Script2Script
+/** @}*/   //addtogroup ScriptSideAPIs
+
+} // namespace Script2Script