Continue documenting Script and make some functions private

engine/src/script/script.hpp

@@ -176,29 +176,50 @@ struct Script
 	/// @param remote The remote script
 	void setup_strict_remote_calls_to(Script& remote);
 
-	void add_allowed_remote_function(gaddr_t addr)
-	{
-		m_remote_access.insert(addr);
-	}
+	/// @brief Allow a remote Script to call the given local function on this Script instance.
+	/// Only applies if setup_strict_remote_calls_to() is used on the caller Script.
+	/// @param func The local function on this instance to allow remote callers to call.
+	void add_allowed_remote_function(const std::string& func);
+	void add_allowed_remote_function(gaddr_t addr);
 
 	/* The guest heap is managed outside using system calls. */
+
+	/// @brief Allocate bytes inside the program. All allocations are at least 8-byte aligned.
+	/// @param bytes The number of 8-byte aligned bytes to allocate.
+	/// @return The address of the allocated bytes.
 	gaddr_t guest_alloc(gaddr_t bytes);
+
+	/// @brief Allocate bytes inside the program. All allocations are at least 8-byte aligned.
+	/// This allocation is sequentially accessible outside of the script. Using
+	/// this function the host engine can view and use the allocation as a single
+	/// consecutive array of bytes, allowing it to be used with many (if not most)
+	/// APIs that do not handle fragmented memory.
+	/// @param bytes The number of sequentially allocated 8-byte aligned bytes.
+	/// @return The address of the sequentially allocated bytes.
 	gaddr_t guest_alloc_sequential(gaddr_t bytes);
 	bool guest_free(gaddr_t addr);
 
-	/* Allocate n uninitialized objects in the guest and return the
-	   location. A managing object is returned, which will free all
-	   objects on destruction. The object can be moved. */
+	/// @brief Create a wrapper object that manages an allocation of n objects of type T
+	/// inside the program. All objects are default-constructed.
+	/// All objects are accessible in the host and in the script. The script can read and write
+	/// all objects at will, making the state of these objects fundamentally untrustable.
+	/// When the wrapper destructs, the allocation in the program is also freed. Can be moved.
+	/// @tparam T The type of the allocated objects.
+	/// @param n The number of allocated objects in the array.
+	/// @return A wrapper managing the program-hosted objects. Can be moved.
 	template <typename T> GuestObjects<T> guest_alloc(size_t n = 1);
 
-	void
-	gdb_remote_debugging(std::string message, bool one_up, uint16_t port = 0);
+	/// @brief Start debugging with GDB right now. Only works on Linux.
+	/// @param message Message to print inside GDB.
+	/// @param one_up Always go one stack frame up? This can be used to leave a wrapper function.
+	/// @param port The port to use. By default the RSP port 2159.
+	void gdb_remote_debugging(std::string message, bool one_up, uint16_t port = 0);
 
+	/// @brief Decide what happens when Game::exit() is called in the script.
+	/// @param callback The function to call when Game::exit() is called.
 	static void on_exit(exit_func_t callback) { Script::m_exit = std::move(callback); }
 	void exit() { Script::m_exit(*this); } // Called by Game::exit() from the script.
 
-	static void setup_syscall_interface();
-	bool initialize();
 	// Create new Script instance from file
 	Script(
 		const std::string& name, const std::string& filename,
@@ -212,6 +233,8 @@ struct Script
 	~Script();
 
   private:
+	static void setup_syscall_interface();
+	bool initialize();
 	void could_not_find(std::string_view);
 	void handle_exception(gaddr_t);
 	void handle_timeout(gaddr_t);
@@ -435,3 +458,16 @@ template <typename T> inline GuestObjects<T> Script::guest_alloc(size_t n)
 	}
 	throw std::runtime_error("Unable to allocate aligned sequential data");
 }
+
+inline void Script::add_allowed_remote_function(gaddr_t addr)
+{
+	m_remote_access.insert(addr);
+}
+inline void Script::add_allowed_remote_function(const std::string& func)
+{
+	const auto addr = this->address_of(func);
+	if (addr != 0x0)
+		this->m_remote_access.insert(addr);
+	else
+		throw std::runtime_error("No such function: " + func);
+}