1.1 --- a/sourcepawn/include/sp_vm_api.h Thu Jan 04 02:08:27 2007 +0000
1.2 +++ b/sourcepawn/include/sp_vm_api.h Thu Jan 04 20:43:28 2007 +0000
1.3 @@ -24,7 +24,7 @@
1.4 {
1.5 public:
1.6 /**
1.7 - * Given a code pointer, finds the file it is associated with.
1.8 + * @brief Given a code pointer, finds the file it is associated with.
1.9 *
1.10 * @param addr Code address offset.
1.11 * @param filename Pointer to store filename pointer in.
1.12 @@ -32,7 +32,7 @@
1.13 virtual int LookupFile(ucell_t addr, const char **filename) =0;
1.14
1.15 /**
1.16 - * Given a code pointer, finds the function it is associated with.
1.17 + * @brief Given a code pointer, finds the function it is associated with.
1.18 *
1.19 * @param addr Code address offset.
1.20 * @param name Pointer to store function name pointer in.
1.21 @@ -40,7 +40,7 @@
1.22 virtual int LookupFunction(ucell_t addr, const char **name) =0;
1.23
1.24 /**
1.25 - * Given a code pointer, finds the line it is associated with.
1.26 + * @brief Given a code pointer, finds the line it is associated with.
1.27 *
1.28 * @param addr Code address offset.
1.29 * @param line Pointer to store line number in.
1.30 @@ -57,28 +57,28 @@
1.31 virtual ~IPluginContext() { };
1.32 public:
1.33 /**
1.34 - * Returns the parent IVirtualMachine.
1.35 + * @brief Returns the parent IVirtualMachine.
1.36 *
1.37 * @return Parent virtual machine pointer.
1.38 */
1.39 virtual IVirtualMachine *GetVirtualMachine() =0;
1.40
1.41 /**
1.42 - * Returns the child sp_context_t structure.
1.43 + * @brief Returns the child sp_context_t structure.
1.44 *
1.45 * @return Child sp_context_t structure.
1.46 */
1.47 virtual sp_context_t *GetContext() =0;
1.48
1.49 /**
1.50 - * Returns true if the plugin is in debug mode.
1.51 + * @brief Returns true if the plugin is in debug mode.
1.52 *
1.53 * @return True if in debug mode, false otherwise.
1.54 */
1.55 virtual bool IsDebugging() =0;
1.56
1.57 /**
1.58 - * Installs a debug break and returns the old one, if any.
1.59 + * @brief Installs a debug break and returns the old one, if any.
1.60 * This will fail if the plugin is not debugging.
1.61 *
1.62 * @param newpfn New function pointer.
1.63 @@ -87,24 +87,24 @@
1.64 virtual int SetDebugBreak(SPVM_DEBUGBREAK newpfn, SPVM_DEBUGBREAK *oldpfn) =0;
1.65
1.66 /**
1.67 - * Returns debug info.
1.68 + * @brief Returns debug info.
1.69 *
1.70 * @return IPluginDebugInfo, or NULL if no debug info found.
1.71 */
1.72 virtual IPluginDebugInfo *GetDebugInfo() =0;
1.73
1.74 /**
1.75 - * Allocs memory on the secondary stack of a plugin.
1.76 + * @brief Allocs memory on the secondary stack of a plugin.
1.77 * Note that although called a heap, it is in fact a stack.
1.78 *
1.79 * @param cells Number of cells to allocate.
1.80 - * @param local_adddr Will be filled with data offset to heap.
1.81 + * @param local_addr Will be filled with data offset to heap.
1.82 * @param phys_addr Physical address to heap memory.
1.83 */
1.84 virtual int HeapAlloc(unsigned int cells, cell_t *local_addr, cell_t **phys_addr) =0;
1.85
1.86 /**
1.87 - * Pops a heap address off the heap stack. Use this to free memory allocated with
1.88 + * @brief Pops a heap address off the heap stack. Use this to free memory allocated with
1.89 * SP_HeapAlloc().
1.90 * Note that in SourcePawn, the heap is in fact a bottom-up stack. Deallocations
1.91 * with this native should be performed in precisely the REVERSE order.
1.92 @@ -114,7 +114,7 @@
1.93 virtual int HeapPop(cell_t local_addr) =0;
1.94
1.95 /**
1.96 - * Releases a heap address using a different method than SP_HeapPop().
1.97 + * @brief Releases a heap address using a different method than SP_HeapPop().
1.98 * This allows you to release in any order. However, if you allocate N
1.99 * objects, release only some of them, then begin allocating again,
1.100 * you cannot go back and starting freeing the originals.
1.101 @@ -127,7 +127,7 @@
1.102 virtual int HeapRelease(cell_t local_addr) =0;
1.103
1.104 /**
1.105 - * Finds a native by name.
1.106 + * @brief Finds a native by name.
1.107 *
1.108 * @param name Name of native.
1.109 * @param index Optionally filled with native index number.
1.110 @@ -135,7 +135,7 @@
1.111 virtual int FindNativeByName(const char *name, uint32_t *index) =0;
1.112
1.113 /**
1.114 - * Gets native info by index.
1.115 + * @brief Gets native info by index.
1.116 *
1.117 * @param index Index number of native.
1.118 * @param native Optionally filled with pointer to native structure.
1.119 @@ -143,14 +143,14 @@
1.120 virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0;
1.121
1.122 /**
1.123 - * Gets the number of natives.
1.124 + * @brief Gets the number of natives.
1.125 *
1.126 * @return Filled with the number of natives.
1.127 */
1.128 virtual uint32_t GetNativesNum() =0;
1.129
1.130 /**
1.131 - * Finds a public function by name.
1.132 + * @brief Finds a public function by name.
1.133 *
1.134 * @param name Name of public
1.135 * @param index Optionally filled with public index number.
1.136 @@ -158,29 +158,30 @@
1.137 virtual int FindPublicByName(const char *name, uint32_t *index) =0;
1.138
1.139 /**
1.140 - * Gets public function info by index.
1.141 + * @brief Gets public function info by index.
1.142 *
1.143 * @param index Public function index number.
1.144 - * @param public Optionally filled with pointer to public structure.
1.145 + * @param publicptr Optionally filled with pointer to public structure.
1.146 */
1.147 virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0;
1.148
1.149 /**
1.150 - * Gets the number of public functions.
1.151 + * @brief Gets the number of public functions.
1.152 *
1.153 * @return Filled with the number of public functions.
1.154 */
1.155 virtual uint32_t GetPublicsNum() =0;
1.156
1.157 /**
1.158 - * Gets public variable info by index.
1.159 + * @brief Gets public variable info by index.
1.160 + *
1.161 * @param index Public variable index number.
1.162 * @param pubvar Optionally filled with pointer to pubvar structure.
1.163 */
1.164 virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0;
1.165
1.166 /**
1.167 - * Finds a public variable by name.
1.168 + * @brief Finds a public variable by name.
1.169 *
1.170 * @param name Name of pubvar
1.171 * @param index Optionally filled with pubvar index number.
1.172 @@ -188,23 +189,23 @@
1.173 virtual int FindPubvarByName(const char *name, uint32_t *index) =0;
1.174
1.175 /**
1.176 - * Gets the addresses of a public variable.
1.177 - *
1.178 - * @param index Index of public variable.
1.179 - * @param local_addr Address to store local address in.
1.180 - * @param phys_addr Address to store physically relocated in.
1.181 - */
1.182 + * @brief Gets the addresses of a public variable.
1.183 + *
1.184 + * @param index Index of public variable.
1.185 + * @param local_addr Address to store local address in.
1.186 + * @param phys_addr Address to store physically relocated in.
1.187 + */
1.188 virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0;
1.189
1.190 /**
1.191 - * Returns the number of public variables.
1.192 + * @brief Returns the number of public variables.
1.193 *
1.194 * @return Number of public variables.
1.195 */
1.196 virtual uint32_t GetPubVarsNum() =0;
1.197
1.198 /**
1.199 - * Round-about method of converting a plugin reference to a physical address
1.200 + * @brief Round-about method of converting a plugin reference to a physical address
1.201 *
1.202 * @param local_addr Local address in plugin.
1.203 * @param phys_addr Optionally filled with relocated physical address.
1.204 @@ -212,7 +213,7 @@
1.205 virtual int LocalToPhysAddr(cell_t local_addr, cell_t **phys_addr) =0;
1.206
1.207 /**
1.208 - * Converts a local address to a physical string.
1.209 + * @brief Converts a local address to a physical string.
1.210 *
1.211 * @param local_addr Local address in plugin.
1.212 * @param addr Destination output pointer.
1.213 @@ -220,7 +221,7 @@
1.214 virtual int LocalToString(cell_t local_addr, char **addr) =0;
1.215
1.216 /**
1.217 - * Converts a physical string to a local address.
1.218 + * @brief Converts a physical string to a local address.
1.219 *
1.220 * @param local_addr Local address in plugin.
1.221 * @param bytes Number of chars to write, including NULL terminator.
1.222 @@ -229,29 +230,29 @@
1.223 virtual int StringToLocal(cell_t local_addr, size_t bytes, const char *source) =0;
1.224
1.225 /**
1.226 - * Converts a physical UTF-8 string to a local address.
1.227 - * This function is the same as the ANSI version, except it will copy the maximum number of characters possible
1.228 - * without accidentally chopping a multi-byte character.
1.229 - *
1.230 - * @param local_addr Local address in plugin.
1.231 - * @param maxbytes Number of bytes to write, including NULL terminator.
1.232 - * @param source Source string to copy.
1.233 - * @param wrtnbytes Optionally set to the number of actual bytes written.
1.234 - */
1.235 + * @brief Converts a physical UTF-8 string to a local address.
1.236 + * This function is the same as the ANSI version, except it will copy the maximum number of characters possible
1.237 + * without accidentally chopping a multi-byte character.
1.238 + *
1.239 + * @param local_addr Local address in plugin.
1.240 + * @param maxbytes Number of bytes to write, including NULL terminator.
1.241 + * @param source Source string to copy.
1.242 + * @param wrtnbytes Optionally set to the number of actual bytes written.
1.243 + */
1.244 virtual int StringToLocalUTF8(cell_t local_addr,
1.245 size_t maxbytes,
1.246 const char *source,
1.247 size_t *wrtnbytes) =0;
1.248
1.249 /**
1.250 - * Pushes a cell onto the stack. Increases the parameter count by one.
1.251 + * @brief Pushes a cell onto the stack. Increases the parameter count by one.
1.252 *
1.253 * @param value Cell value.
1.254 */
1.255 virtual int PushCell(cell_t value) =0;
1.256
1.257 /**
1.258 - * Pushes an array of cells onto the stack. Increases the parameter count by one.
1.259 + * @brief Pushes an array of cells onto the stack. Increases the parameter count by one.
1.260 * If the function returns an error it will fail entirely, releasing anything allocated in the process.
1.261 * Note that this does not release the heap, so you should release it after
1.262 * calling Execute().
1.263 @@ -264,7 +265,7 @@
1.264 virtual int PushCellArray(cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells) =0;
1.265
1.266 /**
1.267 - * Pushes a string onto the stack (by reference) and increases the parameter count by one.
1.268 + * @brief Pushes a string onto the stack (by reference) and increases the parameter count by one.
1.269 * Note that this does not release the heap, so you should release it after
1.270 * calling Execute().
1.271 *
1.272 @@ -275,7 +276,7 @@
1.273 virtual int PushString(cell_t *local_addr, char **phys_addr, const char *string) =0;
1.274
1.275 /**
1.276 - * Individually pushes each cell of an array of cells onto the stack. Increases the
1.277 + * @brief Individually pushes each cell of an array of cells onto the stack. Increases the
1.278 * parameter count by the number of cells pushed.
1.279 * If the function returns an error it will fail entirely, releasing anything allocated in the process.
1.280 *
1.281 @@ -285,7 +286,7 @@
1.282 virtual int PushCellsFromArray(cell_t array[], unsigned int numcells) =0;
1.283
1.284 /**
1.285 - * Binds a list of native names and their function pointers to a context.
1.286 + * @brief Binds a list of native names and their function pointers to a context.
1.287 * If num is 0, the list is read until an entry with a NULL name is reached.
1.288 * If overwrite is non-zero, already registered natives will be overwritten.
1.289 *
1.290 @@ -296,7 +297,7 @@
1.291 virtual int BindNatives(sp_nativeinfo_t *natives, unsigned int num, int overwrite) =0;
1.292
1.293 /**
1.294 - * Binds a single native. Overwrites any existing bind.
1.295 + * @brief Binds a single native. Overwrites any existing bind.
1.296 * If the context does not contain the native that will be binded the function will return
1.297 * with a SP_ERROR_NOT_FOUND error.
1.298 *
1.299 @@ -305,14 +306,14 @@
1.300 virtual int BindNative(sp_nativeinfo_t *native) =0;
1.301
1.302 /**
1.303 - * Binds a single native to any non-registered native.
1.304 + * @brief Binds a single native to any non-registered native.
1.305 *
1.306 * @param native Native to bind.
1.307 */
1.308 virtual int BindNativeToAny(SPVM_NATIVE_FUNC native) =0;
1.309
1.310 /**
1.311 - * Executes a function ID located in this context.
1.312 + * @brief Executes a function ID located in this context.
1.313 *
1.314 * @param funcid Function id to execute.
1.315 * @param result Pointer to store the return value (required).
1.316 @@ -504,7 +505,7 @@
1.317 * @param listener Pointer to an IDebugListener.
1.318 * @return Old IDebugListener, or NULL if none.
1.319 */
1.320 - virtual IDebugListener *SetDebugListener(IDebugListener *pListener) =0;
1.321 + virtual IDebugListener *SetDebugListener(IDebugListener *listener) =0;
1.322
1.323 /**
1.324 * @brief Returns the number of plugins on the call stack.
