Merge pull request #358 from NotAdam/develop

doxygen & some documentation

.gitignore

@@ -121,3 +121,7 @@ cotire/
 
 *objects.txt
 *exports.def
+
+# doxygen output folder
+doxygen/generated/
+doxygen/*.tmp

doxygen/extra_stylesheet.css

@@ -0,0 +1,129 @@
+body {
+	background-color: #222;
+	color: #ccc; 
+	overflow-x: hidden;
+}
+
+#nav-tree {
+	background-color: #222;
+	background-image: none;
+}
+
+#side-nav {
+	width: 300px;
+}
+
+#titlearea {
+	border: none;
+	padding: 5px;
+}
+
+div.header {
+	background-color: #2a2a2a !important;
+}
+
+h2.groupheader {
+	color: #ccc;
+}
+
+.mdescLeft, .mdescRight, .memItemLeft, .memItemRight, .memTemplItemLeft, .memTemplItemRight, .memTemplParams {
+	background-color: #333;
+	color: #ccc;
+}
+
+.directory tr.even {
+	background-color: #3f3f3f;
+}
+
+a, .contents a:visited {
+	color: #548cff;
+}
+
+.memtitle {
+	background-color: #555 !important;
+	background-image: none;
+
+    border-top: 1px solid #717171;
+    border-left: 1px solid #717171;
+    border-right: 1px solid #717171;
+}
+
+.memdoc, dl.reflist dd {
+	background-color: #444;
+
+    border-bottom: 1px solid #717171;
+    border-left: 1px solid #717171;
+    border-right: 1px solid #717171;
+}
+
+.memproto, dl.reflist dt {
+	background-color: #555;
+	color: #ccc;
+	text-shadow: 0px 1px 1px rgba(0, 0, 0, 0.9);
+
+	border-top: 1px solid #717171;
+    border-left: 1px solid #717171;
+    border-right: 1px solid #717171;
+}
+
+div.header {
+	border-bottom: 1px solid #717171;
+	background-image: none;
+}
+
+.paramname {
+	color: #ff5a5a;
+}
+
+.memtemplate {
+	color: #6e9eff;
+}
+
+.memSeparator, h2.groupheader {
+	border-bottom: 1px solid #545454;
+}
+
+.navelem, .navpath ul {
+	background-color: #333;
+	background-image: none;
+}
+
+.navpath ul {
+	border: solid 1px #717171;
+}
+
+.navpath li.footer {
+	color: #548cff;
+}
+
+.navpath li.navelem a, .navpath li.navelem a:visited {
+	color: #ccc;
+	text-shadow: 0px 1px 1px rgba(0, 0, 0, 0.9);
+}
+
+.ui-resizable-e {
+	background-image: none;
+	background-color: #717171;
+}
+
+.sm-dox {
+	background-image: none;
+	background-color: #333;
+}
+
+.sm-dox a {
+	color: #ccc;
+    text-shadow: 0px 1px 1px #000;
+}
+
+.sm-dox a span.sub-arrow {
+	border-color: #ccc transparent transparent transparent;
+}
+
+.sm-dox a, .sm-dox a:focus, .sm-dox a:active, .sm-dox a:hover, .sm-dox a.highlighted {
+	background-image: none;
+}
+
+#main-nav {
+	border-top: 1px solid #717171;
+}

doxygen/pages/index.md

@@ -0,0 +1,6 @@
+# Sapphire Developer Documentation
+The intent is to provide developers with a sense of pride and enjoyment for documenting their code.
+
+Please look forward to it.
+
+![pls](https://i.imgur.com/O8NBR9X.png)

src/common/Network/CommonActorControl.h

@@ -17,7 +17,12 @@ namespace Core {
 
          enum ActorControlType : uint16_t
          {
+            /*! Toggles weapon status -> Sheathed/UnSheathed
+                \param param1 status 0|1 */
             ToggleWeapon = 0x00,
+            /*! Toggles Autoattack status on/off
+                \param param1 status 0|1 */
+            AutoAttack = 0x01,
             SetStatus = 0x02,
             CastStart = 0x03,
             ToggleAggro = 0x04,

src/servers/sapphire_zone/Script/NativeScriptApi.h

@@ -15,10 +15,14 @@
 
 using namespace Core;
 
+// todo: this is shit
 // constant script ids for certain events
 #define EVENTSCRIPT_AETHERYTE_ID 0x50000
 #define EVENTSCRIPT_AETHERNET_ID 0x50001
 
+/*!
+ * @brief The base class that any script should inherit from and set the type param accordingly
+ */
 class ScriptObject
 {
 protected:
@@ -26,16 +30,30 @@ protected:
    std::size_t m_type;
 
 public:
+   /*!
+    * @param id an ID which uniquely identifies this script in relation to it's type
+    * @param type The RTTI hash code of the implementing type to uniquely identify it
+    */
    ScriptObject( uint32_t id, std::size_t type ) :
       m_id( id ),
       m_type( type )
    { }
 
+   /*!
+    * @brief Gets the ID set for this script
+    *
+    * @return The allocated ID of the script set during object construction
+    */
    virtual uint32_t getId() const
    {
       return m_id;
    }
 
+   /*!
+    * @brief Gets the unique identifier (hash_code) of the script
+    *
+    * @return The hash_code of the script
+    */
    virtual std::size_t getType() const
    {
       return m_type;
@@ -43,6 +61,9 @@ public:
 };
 
 
+/*!
+ * @brief The base class for any scripts that implement behaviour related to status effects.
+ */
 class StatusEffectScript : public ScriptObject
 {
 public:
@@ -50,17 +71,68 @@ public:
       ScriptObject( effectId, typeid( StatusEffectScript ).hash_code() )
    { }
 
+   /*!
+    * @brief Called on each tick that a status effect is active on an actor
+    *
+    * @param actor the actor the status effect is ticking on
+    */
    virtual void onTick( Entity::Chara& actor ) { }
+
+   /*!
+    * @brief Called when the status effect is applied to an actor
+    *
+    * @param actor the actor on which the status effect was applied to
+    */
    virtual void onApply( Entity::Chara& actor ) { }
+
+   /*!
+    * @brief Called when the actor (usually a player) removes the status effect by right clicking it
+    *
+    * @param actor The actor on which the effect was removed from
+    */
    virtual void onRemove( Entity::Chara& actor ) { }
+
+   /*!
+    * @brief Called when the status effect expires
+    *
+    * @param actor The actor on which the efect expired on
+    */
    virtual void onExpire( Entity::Chara& actor ) { }
+
+   /*!
+    * @brief Called when the player with the status effect collides with another player, eg. hot potato
+    *
+    * @param actor The actor which has status effect
+    * @param actorHit The actor who collided with the status effect owner
+    */
    virtual void onPlayerCollision( Entity::Chara& actor, Entity::Chara& actorHit ) { }
+
+   /*!
+    * @brief Called when the owner finishes a cast
+    *
+    * @param actor The actor who finished a cast
+    */
    virtual void onPlayerFinishCast( Entity::Chara& actor ) { }
+
+   /*!
+    * @brief Called when the status effect owner was damaged
+    *
+    * @param actor The actor that was damaged
+    */
    virtual void onPlayerDamaged( Entity::Chara& actor ) { }
+
+   /*!
+    * @brief Called when the status effect owner dies
+    *
+    * @param actor The actor that died
+    */
    virtual void onPlayerDeath( Entity::Chara& actor ) { }
 };
 
 
+/*!
+ * @brief The base class for any scripts that implement behaviour related to actions
+ */
 class ActionScript : public ScriptObject
 {
 public:
@@ -74,6 +146,10 @@ public:
 };
 
 
+/*!
+ * @brief The base class for any scripts that implement behaviour related to the event system.
+ * This includes but is not limited to: NPCs, shops, some world objects
+ */
 class EventScript : public ScriptObject
 {
 protected:
@@ -99,6 +175,9 @@ public:
 };
 
 
+/*!
+ * @brief The base class for any scripts that implement behaviour related to BattleNPCs
+ */
 class BattleNpcScript : public ScriptObject
 {
 public:
@@ -107,6 +186,9 @@ public:
    { }
 };
 
+/*!
+ * @brief The base class for any scripts that implement behaviour related to zones
+ */
 class ZoneScript : public ScriptObject
 {
 public:
@@ -117,6 +199,9 @@ public:
    virtual void onZoneInit() { }
 };
 
+/*!
+ * @brief The base class for any scripts that implement behaviour related to instance content zones
+ */
 class InstanceContentScript : public ScriptObject
 {
 public:

src/servers/sapphire_zone/Script/NativeScriptMgr.h

@@ -13,30 +13,101 @@
 namespace Core {
 namespace Scripting {
 
+   /*!
+    * @brief Contains all the functionality for easily loading, unloading, reloading and generally accessing scripts.
+    */
    class NativeScriptMgr
    {
    protected:
+      /*!
+       * @brief An internal list that maps script types to another list containing scripts indexed by their assoicated id
+       */
       std::unordered_map< std::size_t, std::unordered_map< uint32_t, ScriptObject* > > m_scripts;
 
+
       ScriptLoader m_loader;
 
+      /*!
+       * @brief The queue that scripts to be reloaded are placed into.
+       */
       std::queue< std::string > m_scriptLoadQueue;
 
+      /*!
+       * @brief Used to unload a script
+       *
+       * Used to unload a script, clears m_scripts of any scripts assoicated with a ScriptInfo and then unloads that module
+       *
+       * @param info A pointer to the ScriptInfo object that is to be erased
+       * @return true if successful, false if not
+       */
       bool unloadScript( ScriptInfo* info );
 
    public:
       NativeScriptMgr() = default;
 
+      /*!
+       * @brief Loads a script from a path
+       *
+       * This will populate m_scripts if it is successful and scripts will be available as soon as this returns.
+       *
+       * @param path The path to the module to load
+       * @return true if successful, false if not
+       */
       bool loadScript( const std::string& path );
+
+      /*!
+       * @brief Unloads a script
+       *
+       * @param name The module name of the script to unload
+       * @return true if successful
+       */
       bool unloadScript( const std::string& name );
+
+      /*!
+       * @brief Queues a script module to be reloaded
+       *
+       * Due to the nature of how this works, there's no return.
+       * It will just silently fail over and over again to infinity and beyond until the server restarts... not that should ever happen under normal circumstances.
+       *
+       * @param name The name of the module to be reloaded.
+       */
       void queueScriptReload( const std::string& name );
+
+      /*!
+       * @brief Case-insensitive search for modules, useful for debug commands
+       *
+       * @param scripts a set of ScriptInfo ptrs
+       * @param search the search term
+       */
       void findScripts( std::set< Core::Scripting::ScriptInfo* >& scripts, const std::string& search );
 
+      /*!
+       * @brief Called on a regular interval, allows for scripts to be loaded from the internal load queue.
+       */
       void processLoadQueue();
 
+      /*!
+       * @brief Gets the module file extention for the current platform (windows, linux, osx)
+       *
+       * @return The file extension for the current platform
+       */
       const std::string getModuleExtension();
+
+      /*!
+       * @brief Checks to see if a module with the specified name exists
+       *
+       * @param name The module name to lookup
+       * @return true if loaded, false if not
+       */
       bool isModuleLoaded( const std::string& name );
 
+      /*!
+       * @brief Get a specific script from the internal table
+       *
+       * @tparam T The type of the script to search for
+       * @param scriptId The ID of the script to search for
+       * @return T* if successful, nullptr if the script doesn't exist
+       */
       template< typename T >
       T* getScript( uint32_t scriptId )
       {
@@ -51,7 +122,11 @@ namespace Scripting {
    };
 
 
-
+   /*!
+    * @brief Creates an instance of NativeScriptMgr
+    *
+    * @return a boost::shared_ptr to NativeScriptMgr
+    */
    boost::shared_ptr< NativeScriptMgr > createNativeScriptMgr();
 } }
 

src/servers/sapphire_zone/Script/ScriptInfo.h

@@ -16,16 +16,48 @@ typedef void* ModuleHandle;
 namespace Core {
 namespace Scripting {
 
+   /*!
+    * @brief An internal class used to track information about loaded modules and their scripts.
+    *
+    * The main purpose of this is to maintain easy access to the module handle and the pointers to scripts that are loaded.
+    * Furthermore, allows for quick and easy cross platform access to the module paths associated with the runtime module cache and its original path.
+    */
    class ScriptInfo
    {
    public:
       ScriptInfo() = default;
 
+      /*!
+       * @brief The file name of the loaded library.
+       *
+       * On all platforms, this will be the full filename of the module, eg:
+       * - script_instances.dll on Windows
+       * - libscript_instances.so on Linux
+       */
       std::string library_name;
+
+      /*!
+       * @brief The path to the module currently loaded in memory from the cached location.
+       */
       std::string cache_path;
+
+      /*!
+       * @brief The original path of the module before it was copied to the cache location.
+       */
       std::string library_path;
 
+      /*!
+       * @brief A handle to the module.
+       *
+       * The underlying type for this depends on platform. On Windows it's some stupid shit, on everything else it's a void*.
+       */
       ModuleHandle handle;
+
+      /*!
+       * @brief An internal list of all the pointers to each ScriptObject
+       *
+       * This is tracked so when we unload this module we can call delete on each ScriptObject and correctly free it from memory.
+       */
       std::vector< ScriptObject* > scripts;
    };
 }

src/servers/sapphire_zone/Script/ScriptLoader.cpp

@@ -14,9 +14,6 @@ extern Core::Framework g_fw;
 
 namespace fs = boost::filesystem;
 
-Core::Scripting::ScriptLoader::ScriptLoader()
-{}
-
 const std::string Core::Scripting::ScriptLoader::getModuleExtension()
 {
 #ifdef _WIN32

src/servers/sapphire_zone/Script/ScriptLoader.h

@@ -1,7 +1,6 @@
 #ifndef CORE_SCRIPTLOADER_H
 #define CORE_SCRIPTLOADER_H
 
-#include <string>
 #include <unordered_map>
 #include <set>
 
@@ -21,28 +20,87 @@ using ModuleHandle = void*;
 namespace Core {
 namespace Scripting {
 
+   /*!
+    * @brief Provides low level functionality for loading modules on different platforms along with managing those loaded modules.
+    */
    class ScriptLoader
    {
    protected:
+      /*!
+       * @brief The internal list of all modules that are loaded.
+       */
       std::unordered_map< std::string, ScriptInfo* > m_scriptMap;
 
+      /*!
+       * @brief Unload a loaded module from it's ModuleHandle
+       *
+       * @return true if the unload was successful, false if not
+       */
       bool unloadModule( ModuleHandle );
 
    public:
-      ScriptLoader();
+      ScriptLoader() = default;
 
+      /*!
+       * @brief Gets the module file extention for the current platform (windows, linux, osx)
+       *
+       * @return The file extension for the current platform
+       */
       const std::string getModuleExtension();
+
+      /*!
+       * @brief Load a module from a path
+       *
+       * Internally, this will also copy the module from it's original folder into the cache folder.
+       *
+       * @return A pointer to ScriptInfo if the load was successful, nullptr if it failed
+       */
       ScriptInfo* loadModule( const std::string& );
 
+      /*!
+       * @brief Unload a script from it's ScriptInfo object
+       *
+       * @return true if successful, false if not
+       */
       bool unloadScript( ScriptInfo* );
+
+      /*!
+       * @brief Unload a script via it's module handle
+       *
+       * @return true if successful, false if not
+       */
       bool unloadScript( ModuleHandle );
 
+      /*!
+       * @brief Look up a ScriptInfo* by a module name
+       *
+       * @param name The exact module name to search for, case-sensitive
+       * @return The ScriptInfo ptr if successful, nullptr if it wasn't found
+       */
       ScriptInfo* getScriptInfo( std::string name );
 
+      /*!
+       * @brief Get all scripts assoicated with a module
+       *
+       * @param handle The handle to the module
+       * @return An array of unknown size ending with nullptr if success, nullptr if not
+       */
       ScriptObject** getScripts( ModuleHandle handle );
 
+      /*!
+       * @brief Checks to see if a module with the specified name exists
+       *
+       * @param name The module name to lookup
+       * @return true if loaded, false if not
+       */
       bool isModuleLoaded( std::string name );
 
+      /*!
+       * @brief Case-insensitive search for modules, useful for debug commands
+       *
+       * @param scripts a set of ScriptInfo ptrs
+       * @param search the search term
+       */
       void findScripts( std::set< Core::Scripting::ScriptInfo* >& scripts, const std::string& search );
    };
 

src/servers/sapphire_zone/Script/ScriptMgr.h

@@ -16,23 +16,41 @@ namespace Core
       class ScriptMgr
       {
       private:
-
+         /*!
+          * @brief A shared ptr to NativeScriptMgr, used for accessing and managing the native script system.
+          */
          boost::shared_ptr< NativeScriptMgr > m_nativeScriptMgr;
 
          std::function< std::string( Entity::Player& ) > m_onFirstEnterWorld;
-        // auto fn = m_pChaiHandler->eval< std::function<const std::string( Entity::Player ) > >( "onFirstEnterWorld" );
 
+         /*!
+          * @brief Used to ignore the first change notification that Watchdog emits.
+          * Because reasons, it likes to emit an initial notification with all the files that match the filter, we don't want that so we ignore it.
+          */
          bool m_firstScriptChangeNotificiation;
 
       public:
          ScriptMgr();
          ~ScriptMgr();
 
+         /*!
+          * @brief Loads all the script modules and readies the ScriptMgr
+          *
+          * This gets all the modules inside the specified scripts folder and then attempts to load each one.
+          * After that, it starts the directory watcher so the server can reload modules at runtime when changes occur.
+          *
+          * @return true if init success
+          */
          bool init();
-         void reload();
 
+         /*!
+          * @brief Called on each tick or at a regular interval. Allows for the NativeScriptMgr to process module loading and reloading.
+          */
          void update();
 
+         /*!
+          * @brief Registers a directory watcher which allows for script modules to be reloaded when changes to the modules occur
+          */
          void watchDirectories();
 
          void onPlayerFirstEnterWorld( Entity::Player& player );