some more documentation

src/servers/sapphire_zone/Script/NativeScriptMgr.h

@@ -13,30 +13,93 @@
 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;
 
+      /*!
+       * 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;
+      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 );
 
+      /*!
+       * Called on a regular interval, allows for scripts to be loaded from the internal load queue.
+       */
       void processLoadQueue();
 
+      /*!
+       * Gets the module file extention for the current platform (windows, linux, osx)
+       * @return The file extension for the current platform
+       */
       const std::string getModuleExtension();
+
+      /*!
+       * 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 );
 
+      /*!
+       * 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 +114,10 @@ namespace Scripting {
    };
 
 
-
+   /*!
+    * 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,47 @@ typedef void* ModuleHandle;
 namespace Core {
 namespace Scripting {
 
+   /*!
+    * 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;
+
+      /*!
+       * The path to the module currently loaded in memory from the cached location.
+       */
       std::string cache_path;
+
+      /*!
+       * 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;
+
+      /*!
+       * @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.h

@@ -47,7 +47,10 @@ namespace Scripting {
       const std::string getModuleExtension();
 
       /*!
-       * Load a module from a path
+       * @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& );

src/servers/sapphire_zone/Script/ScriptMgr.h

@@ -16,23 +16,41 @@ namespace Core
       class ScriptMgr
       {
       private:
-
+         /*!
+          * 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" );
 
+         /*!
+          * 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();
 
+         /*!
+          * Called on each tick or at a regular interval. Allows for the NativeScriptMgr to process module loading and reloading.
+          */
          void update();
 
+         /*!
+          * 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 );