datapack: Tabs->spaces, consistency, nuke IsPackReadable

plugins/include/datapack.inc

@@ -13,9 +13,16 @@
 #define _datapack_included
 
 /**
- * DataPacks are a way to store and move around various types of data in AMX Mod X Scripting. 
+ * Datapack tag declaration
- * Since some things are not possible in AMX Mod X, such as a function consuming a String, 
+ *
- * DataPacks help us get these Strings and other items where they need to go.
+ * @note Datapacks provide a way to store and move around arbitrary amounts (and
+ *       types) of data in AMX Mox X. Data is packed into a single cell value -
+ *       the DataPack handle. This handle can be passed around more easily, can
+ *       be returned by functions and can simulate advanced concepts like string
+ *       consummation.
+ * @note Plugins are responsible for freeing all datapack handles they acquire.
+ *       Failing to free handles will result in the plugin and AMXX leaking
+ *       memory.
  */
 
 enum DataPack
@@ -26,113 +33,120 @@ enum DataPack
 /**
  * Creates a new datapack.
  *
- * @return			A Handle to the data pack.
+ * @return  New datapack handle, which must be freed via DestroyDataPack().
  */
 native DataPack:CreateDataPack();
 
 /**
- * Packs a normal cell into a data pack.
+ * Packs a cell value into a datapack.
+ *
+ * @param pack      Datapack handle
+ * @param cell      Cell value to pack
  *
- * @param pack		Handle to the data pack.
- * @param cell		Cell to add.
  * @noreturn
- * @error			Invalid handle.
+ * @error           If an invalid handle is provided, an error will be thrown.
  */
 native WritePackCell(DataPack:pack, any:cell);
 
 /**
- * Packs a float into a data pack.
+ * Packs a float value into a datapack.
+ *
+ * @param pack      Datapack handle
+ * @param val       Float value to pack
  *
- * @param pack		Handle to the data pack.
- * @param val		Float to add.
  * @noreturn
- * @error			Invalid handle.
+ * @error           If an invalid handle is provided, an error will be thrown.
  */
 native WritePackFloat(DataPack:pack, Float:val);
 
 /**
  * Packs a string into a datapack.
  *
- * @param pack		Handle to the data pack.
+ * @param pack      Datapack handle
- * @param str		String to add.
+ * @param str       String to pack
- * @return			Length of copied string.
+ *
- * @error			Invalid handle.
+ * @return          Length of copied string
+ * @error           If an invalid handle is provided, an error will be thrown.
  */
 native WritePackString(DataPack:pack, const str[]);
 
 /**
- * Reads a cell from a data pack.
+ * Reads a cell from a Datapack.
  *
- * @param pack		Handle to the data pack.
+ * @param pack      Datapack handle
- * @return			Cell value.
+ *
- * @error			Invalid handle, or bounds error.
+ * @return          Cell value
+ * @error           If an invalid handle is provided, or not enough data is left
+ *                  in the datapack, an error will be thrown.
  */
 native any:ReadPackCell(DataPack:pack);
 
 /**
  * Reads a float from a datapack.
  *
- * @param pack		Handle to the data pack.
+ * @param pack      Datapack handle
- * @return			Float value.
+ *
- * @error			Invalid handle, or bounds error.
+ * @return          Float value
+ * @error           If an invalid handle is provided, or not enough data is left
+ *                  in the datapack, an error will be thrown.
  */
-native Float:ReadPackFloat(DataPack:pack);
+native Float:ReadPackFloat(datapack:pack);
 
 /**
- * Reads a string from a data pack.
+ * Reads a string from a Datapack.
  *
- * @param pack		Handle to the data pack.
+ * @param pack      Datapack handle
- * @param buffer	Destination string buffer.
+ * @param buffer    Buffer to copy string to
- * @param maxlen	Maximum length of output string buffer.
+ * @param maxlen    Maximum size of buffer
- * @return			Length of output string.
+ *
- * @error			Invalid handle, or bounds error.
+ * @return          Number of cells written to buffer
+ * @error           If an invalid handle is provided, or not enough data is left
+ *                  in the datapack, an error will be thrown.
  */
 native ReadPackString(DataPack:pack, buffer[], maxlen);
 
 /**
- * Resets the position in a data pack.
+ * Resets the datapack read/write position to the start.
+ *
+ * @param pack      Datapack handle
+ * @param clear     If true, clears the contained data
  *
- * @param pack		Handle to the data pack.
- * @param clear		If true, clears the contained data.
  * @noreturn
- * @error			Invalid handle.
+ * @error           If an invalid handle is provided, an error will be thrown.
  */
 native ResetPack(DataPack:pack, bool:clear = false);
 
 /**
- * Returns the read or write position in a data pack.
+ * Returns the datapack read/write position.
  *
- * @param pack		Handle to the data pack.
+ * @param pack      Datapack handle
- * @return			Numerical position in the data pack.
+ *
- * @error			Invalid handle.
+ * @return          Position in the datapack
+ * @error           If an invalid handle is provided, an error will be thrown.
  */
 native GetPackPosition(DataPack:pack);
 
 /**
- * Sets the read/write position in a data pack.
+ * Sets the datapack read/write position.
+ *
+ * @note This should only ever be used with (known to be valid) positions
+ *       returned by GetPackPosition(). It is not possible for plugins to safely
+ *       compute datapack positions.
+ *
+ * @param pack      Datapack handle
+ * @param position  New position to set
  *
- * @param pack		Handle to the data pack.
- * @param position	New position to set.
  * @noreturn
- * @error			Invalid handle, or position is beyond the pack bounds.
+ * @error           If an invalid handle is provided, or the new position is
+ *                  out of datapack bounds, an error will be thrown.
  */
 native SetPackPosition(DataPack:pack, position);
 
 /**
- * Returns whether or not a specified number of bytes from the data pack
+ * Destroys the datapack and frees its memory.
- *  position to the end can be read.
  *
- * @param pack		Handle to the data pack.
+ * @param pack      Datapack handle
- * @param bytes		Number of bytes to simulate reading.
- * @return			True if can be read, false otherwise.
- * @error			Invalid handle.
- */
-native bool:IsPackReadable(DataPack:pack, bytes);
-
-/**
- * Disposes of a data pack.
  *
- * @param pack		Handle to the data pack.
+ * @return          True if disposed, false otherwise
- * @return			True if disposed, false otherwise.
  */
 native DestroyDataPack(&DataPack:pack);