diff --git a/sourcepawn/include/sp_vm_api.h b/sourcepawn/include/sp_vm_api.h index f1421743..3a3e01a8 100644 --- a/sourcepawn/include/sp_vm_api.h +++ b/sourcepawn/include/sp_vm_api.h @@ -24,7 +24,7 @@ namespace SourcePawn { public: /** - * Given a code pointer, finds the file it is associated with. + * @brief Given a code pointer, finds the file it is associated with. * * @param addr Code address offset. * @param filename Pointer to store filename pointer in. @@ -32,7 +32,7 @@ namespace SourcePawn virtual int LookupFile(ucell_t addr, const char **filename) =0; /** - * Given a code pointer, finds the function it is associated with. + * @brief Given a code pointer, finds the function it is associated with. * * @param addr Code address offset. * @param name Pointer to store function name pointer in. @@ -40,7 +40,7 @@ namespace SourcePawn virtual int LookupFunction(ucell_t addr, const char **name) =0; /** - * Given a code pointer, finds the line it is associated with. + * @brief Given a code pointer, finds the line it is associated with. * * @param addr Code address offset. * @param line Pointer to store line number in. @@ -57,28 +57,28 @@ namespace SourcePawn virtual ~IPluginContext() { }; public: /** - * Returns the parent IVirtualMachine. + * @brief Returns the parent IVirtualMachine. * * @return Parent virtual machine pointer. */ virtual IVirtualMachine *GetVirtualMachine() =0; /** - * Returns the child sp_context_t structure. + * @brief Returns the child sp_context_t structure. * * @return Child sp_context_t structure. */ virtual sp_context_t *GetContext() =0; /** - * Returns true if the plugin is in debug mode. + * @brief Returns true if the plugin is in debug mode. * * @return True if in debug mode, false otherwise. */ virtual bool IsDebugging() =0; /** - * Installs a debug break and returns the old one, if any. + * @brief Installs a debug break and returns the old one, if any. * This will fail if the plugin is not debugging. * * @param newpfn New function pointer. @@ -87,24 +87,24 @@ namespace SourcePawn virtual int SetDebugBreak(SPVM_DEBUGBREAK newpfn, SPVM_DEBUGBREAK *oldpfn) =0; /** - * Returns debug info. + * @brief Returns debug info. * * @return IPluginDebugInfo, or NULL if no debug info found. */ virtual IPluginDebugInfo *GetDebugInfo() =0; /** - * Allocs memory on the secondary stack of a plugin. + * @brief Allocs memory on the secondary stack of a plugin. * Note that although called a heap, it is in fact a stack. * * @param cells Number of cells to allocate. - * @param local_adddr Will be filled with data offset to heap. + * @param local_addr Will be filled with data offset to heap. * @param phys_addr Physical address to heap memory. */ virtual int HeapAlloc(unsigned int cells, cell_t *local_addr, cell_t **phys_addr) =0; /** - * Pops a heap address off the heap stack. Use this to free memory allocated with + * @brief Pops a heap address off the heap stack. Use this to free memory allocated with * SP_HeapAlloc(). * Note that in SourcePawn, the heap is in fact a bottom-up stack. Deallocations * with this native should be performed in precisely the REVERSE order. @@ -114,7 +114,7 @@ namespace SourcePawn virtual int HeapPop(cell_t local_addr) =0; /** - * Releases a heap address using a different method than SP_HeapPop(). + * @brief Releases a heap address using a different method than SP_HeapPop(). * This allows you to release in any order. However, if you allocate N * objects, release only some of them, then begin allocating again, * you cannot go back and starting freeing the originals. @@ -127,7 +127,7 @@ namespace SourcePawn virtual int HeapRelease(cell_t local_addr) =0; /** - * Finds a native by name. + * @brief Finds a native by name. * * @param name Name of native. * @param index Optionally filled with native index number. @@ -135,7 +135,7 @@ namespace SourcePawn virtual int FindNativeByName(const char *name, uint32_t *index) =0; /** - * Gets native info by index. + * @brief Gets native info by index. * * @param index Index number of native. * @param native Optionally filled with pointer to native structure. @@ -143,14 +143,14 @@ namespace SourcePawn virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0; /** - * Gets the number of natives. + * @brief Gets the number of natives. * * @return Filled with the number of natives. */ virtual uint32_t GetNativesNum() =0; /** - * Finds a public function by name. + * @brief Finds a public function by name. * * @param name Name of public * @param index Optionally filled with public index number. @@ -158,29 +158,30 @@ namespace SourcePawn virtual int FindPublicByName(const char *name, uint32_t *index) =0; /** - * Gets public function info by index. + * @brief Gets public function info by index. * * @param index Public function index number. - * @param public Optionally filled with pointer to public structure. + * @param publicptr Optionally filled with pointer to public structure. */ virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0; /** - * Gets the number of public functions. + * @brief Gets the number of public functions. * * @return Filled with the number of public functions. */ virtual uint32_t GetPublicsNum() =0; /** - * Gets public variable info by index. + * @brief Gets public variable info by index. + * * @param index Public variable index number. * @param pubvar Optionally filled with pointer to pubvar structure. */ virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0; /** - * Finds a public variable by name. + * @brief Finds a public variable by name. * * @param name Name of pubvar * @param index Optionally filled with pubvar index number. @@ -188,23 +189,23 @@ namespace SourcePawn virtual int FindPubvarByName(const char *name, uint32_t *index) =0; /** - * Gets the addresses of a public variable. - * - * @param index Index of public variable. - * @param local_addr Address to store local address in. - * @param phys_addr Address to store physically relocated in. - */ + * @brief Gets the addresses of a public variable. + * + * @param index Index of public variable. + * @param local_addr Address to store local address in. + * @param phys_addr Address to store physically relocated in. + */ virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0; /** - * Returns the number of public variables. + * @brief Returns the number of public variables. * * @return Number of public variables. */ virtual uint32_t GetPubVarsNum() =0; /** - * Round-about method of converting a plugin reference to a physical address + * @brief Round-about method of converting a plugin reference to a physical address * * @param local_addr Local address in plugin. * @param phys_addr Optionally filled with relocated physical address. @@ -212,7 +213,7 @@ namespace SourcePawn virtual int LocalToPhysAddr(cell_t local_addr, cell_t **phys_addr) =0; /** - * Converts a local address to a physical string. + * @brief Converts a local address to a physical string. * * @param local_addr Local address in plugin. * @param addr Destination output pointer. @@ -220,7 +221,7 @@ namespace SourcePawn virtual int LocalToString(cell_t local_addr, char **addr) =0; /** - * Converts a physical string to a local address. + * @brief Converts a physical string to a local address. * * @param local_addr Local address in plugin. * @param bytes Number of chars to write, including NULL terminator. @@ -229,29 +230,29 @@ namespace SourcePawn virtual int StringToLocal(cell_t local_addr, size_t bytes, const char *source) =0; /** - * Converts a physical UTF-8 string to a local address. - * This function is the same as the ANSI version, except it will copy the maximum number of characters possible - * without accidentally chopping a multi-byte character. - * - * @param local_addr Local address in plugin. - * @param maxbytes Number of bytes to write, including NULL terminator. - * @param source Source string to copy. - * @param wrtnbytes Optionally set to the number of actual bytes written. - */ + * @brief Converts a physical UTF-8 string to a local address. + * This function is the same as the ANSI version, except it will copy the maximum number of characters possible + * without accidentally chopping a multi-byte character. + * + * @param local_addr Local address in plugin. + * @param maxbytes Number of bytes to write, including NULL terminator. + * @param source Source string to copy. + * @param wrtnbytes Optionally set to the number of actual bytes written. + */ virtual int StringToLocalUTF8(cell_t local_addr, size_t maxbytes, const char *source, size_t *wrtnbytes) =0; /** - * Pushes a cell onto the stack. Increases the parameter count by one. + * @brief Pushes a cell onto the stack. Increases the parameter count by one. * * @param value Cell value. */ virtual int PushCell(cell_t value) =0; /** - * Pushes an array of cells onto the stack. Increases the parameter count by one. + * @brief Pushes an array of cells onto the stack. Increases the parameter count by one. * If the function returns an error it will fail entirely, releasing anything allocated in the process. * Note that this does not release the heap, so you should release it after * calling Execute(). @@ -264,7 +265,7 @@ namespace SourcePawn virtual int PushCellArray(cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells) =0; /** - * Pushes a string onto the stack (by reference) and increases the parameter count by one. + * @brief Pushes a string onto the stack (by reference) and increases the parameter count by one. * Note that this does not release the heap, so you should release it after * calling Execute(). * @@ -275,7 +276,7 @@ namespace SourcePawn virtual int PushString(cell_t *local_addr, char **phys_addr, const char *string) =0; /** - * Individually pushes each cell of an array of cells onto the stack. Increases the + * @brief Individually pushes each cell of an array of cells onto the stack. Increases the * parameter count by the number of cells pushed. * If the function returns an error it will fail entirely, releasing anything allocated in the process. * @@ -285,7 +286,7 @@ namespace SourcePawn virtual int PushCellsFromArray(cell_t array[], unsigned int numcells) =0; /** - * Binds a list of native names and their function pointers to a context. + * @brief Binds a list of native names and their function pointers to a context. * If num is 0, the list is read until an entry with a NULL name is reached. * If overwrite is non-zero, already registered natives will be overwritten. * @@ -296,7 +297,7 @@ namespace SourcePawn virtual int BindNatives(sp_nativeinfo_t *natives, unsigned int num, int overwrite) =0; /** - * Binds a single native. Overwrites any existing bind. + * @brief Binds a single native. Overwrites any existing bind. * If the context does not contain the native that will be binded the function will return * with a SP_ERROR_NOT_FOUND error. * @@ -305,14 +306,14 @@ namespace SourcePawn virtual int BindNative(sp_nativeinfo_t *native) =0; /** - * Binds a single native to any non-registered native. + * @brief Binds a single native to any non-registered native. * * @param native Native to bind. */ virtual int BindNativeToAny(SPVM_NATIVE_FUNC native) =0; /** - * Executes a function ID located in this context. + * @brief Executes a function ID located in this context. * * @param funcid Function id to execute. * @param result Pointer to store the return value (required). @@ -504,7 +505,7 @@ namespace SourcePawn * @param listener Pointer to an IDebugListener. * @return Old IDebugListener, or NULL if none. */ - virtual IDebugListener *SetDebugListener(IDebugListener *pListener) =0; + virtual IDebugListener *SetDebugListener(IDebugListener *listener) =0; /** * @brief Returns the number of plugins on the call stack.