random touchups that might not be so great

--HG--
extra : convert_revision : svn%3A39bc706e-5318-0410-9160-8a85361fbb7c/trunk%40625

plugins/include/admin.inc

@@ -47,10 +47,10 @@ enum AdminFlag
 	/* --- */
 };
 
-#define AdminFlags_TOTAL	21
+#define AdminFlags_TOTAL	21		/**< Total number of admin flags */
 
 /**
- * These define bitwise values for bitstrings (numbers containing bitwise flags).
+ * @section These define bitwise values for bitstrings (numbers containing bitwise flags).
  */
 #define ADMFLAG_RESERVATION			(1<<0)		/**< Convenience macro for Admin_Reservation as a FlagBit */
 #define ADMFLAG_GENERIC				(1<<1)		/**< Convenience macro for Admin_Generic as a FlagBit */
@@ -74,22 +74,42 @@ enum AdminFlag
 #define ADMFLAG_CUSTOM5				(1<<19)		/**< Convenience macro for Admin_Custom5 as a FlagBit */
 #define ADMFLAG_CUSTOM6				(1<<20)		/**< Convenience macro for Admin_Custom6 as a FlagBit */
 
+/**
+ * @endsection
+ */
+
+/**
+ * @section Hardcoded authentication methods 
+ */
 #define AUTHMETHOD_STEAM			"steam"
 #define AUTHMETHOD_IP				"ip"
 #define AUTHMETHOD_NAME				"name"
 
+/**
+ * @endsection
+ */
+
+/**
+ * Override types.
+ */
 enum OverrideType
 {
 	Override_Command = 1,	/* Command */
 	Override_CommandGroup,	/* Command group */
 };
 
+/**
+ * Override rules.
+ */
 enum OverrideRule
 {
 	Command_Deny = 0,
 	Command_Allow = 1,
 };
 
+/**
+ * Immunity types.
+ */
 enum ImmunityType
 {
 	Immunity_Default = 1,	/* Immune from everyone with no immunity */
@@ -303,8 +323,7 @@ native AdminId:CreateAdmin(const String:name[]="");
 
 /**
  * Retrieves an admin's user name as made with CreateAdmin().
- *
+ * @note This function can return UTF-8 strings, and will safely chop UTF-8 strings.
- * NOTE: This function can return UTF-8 strings, and will safely chop UTF-8 strings.
  *
  * @param id			AdminId of the admin.
  * @param name			String buffer to store name.
@@ -416,8 +435,7 @@ native AdminId:FindAdminByIdentity(const String:auth[], const String:identity[])
 
 /**
  * Removes an admin entry from the cache.
- *
+ * @note This will remove any bindings to a specific user.
- * Note: This will remove any bindings to a specific user.
  *
  * @param id			AdminId index to remove/invalidate.
  * @return				True on success, false otherwise.

plugins/include/clients.inc

@@ -254,7 +254,6 @@ native GetUserFlagBits(client);
  */
 native bool:CanUserTarget(client, target);
 
-
 /** 
  * Creates a fake client.
  *

plugins/include/console.inc

@@ -19,8 +19,8 @@
 #define _console_included
 
 /**
- * Flags for console commands and console variables
+ * @section Flags for console commands and console variables.  The descriptions 
- * @note The descriptions for each constant come directly from the Source SDK.
+ * for each constant come directly from the Source SDK.
  */
 #define FCVAR_NONE				0		/**< The default, no flags at all */
 #define FCVAR_UNREGISTERED		(1<<0)	/**< If this is set, don't add to linked list, etc. */
@@ -52,6 +52,10 @@
 #define FCVAR_NETWORKSYSTEM		(1<<26)	/**< Defined by the network system. */
 #define FCVAR_VPHYSICS			(1<<27)	/**< Defined by vphysics. */
 
+/**
+ * @endsection
+ */
+
 /**
  * Executes a server command as if it were on the server console (or RCON)
  *

plugins/include/core.inc

@@ -72,6 +72,9 @@ enum PluginInfo
 	PlInfo_URL,				/**< Plugin URL */
 };
 
+/**
+ * Defines how an extension must expose itself for autoloading.
+ */
 struct Extension
 {
 	const String:name[],	/* Short name */

plugins/include/entity.inc

@@ -275,6 +275,10 @@ native GetEntDataVector(entity, offset, Float:vec[3]);
  */
 native SetEntDataVector(entity, offset, const Float:vec[3], bool:changeState=false);
 
+/**
+ * @endsection
+ */
+
 /**
  * Given a ServerClass name, finds a networkable send property offset.
  * This information is cached for future calls.

plugins/include/events.inc

@@ -33,6 +33,9 @@ enum EventHookMode
 	EventHookMode_PostNoCopy			/**< Hook callback fired after event is fired, but event data won't be copied */
 };
 
+/**
+ * Hook function types for events.
+ */
 funcenum EventHook
 {
 	/**

plugins/include/files.inc

@@ -18,8 +18,11 @@
 #endif
 #define _files_included
 
-/* @note All paths in SourceMod natives are relative to the mod folder unless otherwise noted. */
+/* @global All paths in SourceMod natives are relative to the mod folder unless otherwise noted. */
- 
+
+/**
+ * File inode types.
+ */
 enum FileType
 {
 	FileType_Unknown = 0,	/* Unknown file type (device/socket) */
@@ -27,15 +30,18 @@ enum FileType
 	FileType_File = 2,		/* File is a file */
 };
 
-#define PLATFORM_MAX_PATH		256
+#define PLATFORM_MAX_PATH		256		/**< Maximum path length. */
 
-#define SEEK_SET 0
+#define SEEK_SET 0						/**< Seek from start. */
-#define SEEK_CUR 1
+#define SEEK_CUR 1						/**< Seek from current position. */
-#define SEEK_END 2
+#define SEEK_END 2						/**< Seek from end position. */
 
+/**
+ * Path types.
+ */
 enum PathType
 {
-	Path_SM,		/* SourceMod root folder */	
+	Path_SM,		/**< SourceMod root folder */	
 };
 
 /**

plugins/include/float.inc

@@ -19,18 +19,14 @@
 #define _float_included
 
 /**
- * @GLOBAL@
+ * Different methods of rounding.
- *   All the trigonometric functions take in or return its values in RADIANS.
- *   Use DegToRad or RadToDeg stocks to convert the radix units.
  */
-
-/* Different methods of rounding */
 enum floatround_method
 {
-	floatround_round = 0,
+	floatround_round = 0,		/**< Standard IEEE rounding */
-	floatround_floor,
+	floatround_floor,			/**< Next lowest integer value. */
-	floatround_ceil,
+	floatround_ceil,			/**< Next highest integer value. */
-	floatround_tozero
+	floatround_tozero			/** Closest integer to zero. */
 };
 
 /**
@@ -164,10 +160,10 @@ native Float:Cosine(Float:value);
 native Float:Tangent(Float:value);
 
 /**
- * Returns the absolute value.
+ * Returns an absolute value.
  *
  * @param value			Input value.
- * @return				abs(value).
+ * @return				Absolute value of the input.
  */
 native Float:FloatAbs(Float:value);
 
@@ -304,11 +300,23 @@ forward operator%(oper1, Float:oper2);
 
 #define FLOAT_PI 3.1415926535897932384626433832795
 
+/**
+ * Converts degrees to radians.
+ *
+ * @param angle		Degrees.
+ * @return			Radians.
+ */
 stock Float:DegToRad(Float:angle)
 {
 	return (angle*FLOAT_PI)/180;
 }
 
+/**
+ * Converts degrees to radians.
+ *
+ * @param angle		Radians.
+ * @return			Degrees.
+ */
 stock Float:RadToDeg(Float:angle)
 {
 	return (angle*180)/FLOAT_PI;

plugins/include/geoip.inc

@@ -21,8 +21,7 @@
 #include <core>
 
 /**
- * @GLOBAL@
+ * @section IP addresses can contain ports, the ports will be stripped out.
- *   IP address can contain ports, the ports will be stripped out.
  */
 
 /**
@@ -53,6 +52,10 @@ native GeoipCode3(const String:ip[], String:ccode[4]);
  */
 native GeoipCountry(const String:ip[], String:name[], len=45);
 
+/**
+ * @endsection
+ */
+
 /**
  * Do not edit below this line!
  */

plugins/include/handles.inc

@@ -18,6 +18,9 @@
 #endif
 #define _handles_included
 
+/**
+ * Handle helper macros.
+ */
 enum Handle
 {
 	INVALID_HANDLE = 0,

plugins/include/sorting.inc

@@ -20,7 +20,7 @@
 #define _sorting_included
 
 /**
- * @brief Contains sorting orders.
+ * Contains sorting orders.
  */
 enum SortOrder
 {

plugins/include/sourcemod.inc

@@ -18,13 +18,16 @@
 #endif
 #define _sourcemod_included
 
+/**
+ * Plugin public information.
+ */
 struct Plugin
 {
-   const String:name[],			/* Plugin Name */
+   const String:name[],			/**< Plugin Name */
-   const String:description[],	/* Plugin Description */
+   const String:description[],	/**< Plugin Description */
-   const String:author[],		/* Plugin Author */
+   const String:author[],		/**< Plugin Author */
-   const String:version[],		/* Plugin Version */
+   const String:version[],		/**< Plugin Version */
-   const String:url[],			/* Plugin URL */
+   const String:url[],			/**< Plugin URL */
 };
 
 #include <core>
@@ -56,7 +59,7 @@ public Plugin:myinfo;
 /**
  * Called when the plugin is fully initialized and all known external references are resolved.
  * This is called even if the plugin type is "private."
- * NOTE: Errors in this function will cause the plugin to stop running.
+ * @note Errors in this function will cause the plugin to stop running.
  *
  * @noreturn
  */
@@ -68,8 +71,8 @@ forward OnPluginStart();
  * not available at this point.  Thus, this forward should only be used for explicit 
  * pre-emptive things, such as adding dynamic natives, or setting certain types of load filters.
  * 
- * NOTE: It is not safe to call externally resolved natives until OnPluginStart().
+ * @note It is not safe to call externally resolved natives until OnPluginStart().
- * NOTE: Any sort of RTE in this function will cause the plugin to fail loading.
+ * @note Any sort of RTE in this function will cause the plugin to fail loading.
  *
  * @param myself	Handle to the plugin.
  * @param late		Whether or not the plugin was loaded "late" (after map load).

plugins/include/string.inc

@@ -19,10 +19,9 @@
 #define _string_included
 
 /**
- * @GLOBAL@
+ * @global Unless otherwise noted, all string functions which take in a writable buffer 
- *   Unless otherwise noted, all string functions which take in a writable buffer and maximum length
+ * and maximum length should have the null terminator INCLUDED in the length.  This means 
- * should have the null terminator INCLUDED in the length.  This means that this is valid:
+ * that this is valid: StrCopy(string, sizeof(string), ...)
- *   StrCopy(string, sizeof(string), ...)
  */
 
 /**
@@ -75,8 +74,8 @@ stock bool:StrEqual(const String:str1[], const String:str2[], bool:caseSensitive
 
 /**
  * Copies one string to another string.
- * NOTE: If the destination buffer is too small to hold the source string,
+ * @note If the destination buffer is too small to hold the source string, the 
- * the destination will be truncated.
+ *       destination will be truncated.
  *
  * @param dest			Destination string buffer to copy to.
  * @param destlen		Destination buffer length (includes null terminator).
@@ -99,7 +98,7 @@ native Format(String:buffer[], maxlength, const String:format[], {Handle,Float,S
 /**
  * Formats a string according to the SourceMod format rules (see documentation).
  * @note This is the same as Format(), except none of the input buffers can overlap the same
- *	    memory as the output buffer.  Since this security check is removed, it is slightly faster.
+ *	     memory as the output buffer.  Since this security check is removed, it is slightly faster.
  *
  * @param buffer		Destination string buffer.
  * @param maxlength		Maximum length of output string buffer.
@@ -112,8 +111,8 @@ native FormatEx(String:buffer[], maxlength, const String:format[], {Handle,Float
 /**
  * Formats a string according to the SourceMod format rules (see documentation).
  * @note This is the same as Format(), except it grabs parameters from a parent parameter
- * stack, rather than a local.  This is useful for implementing your own variable argument
+ *       stack, rather than a local.  This is useful for implementing your own variable 
- * functions.
+ *       argument functions.
  *
  * @param buffer		Destination string buffer.
  * @param maxlength		Maximum length of output string buffer.

plugins/include/textparse.inc

@@ -25,6 +25,9 @@
  * The file format itself is nearly identical to Valve's KeyValues format.
  ********************************/
 
+/**
+ * Parse result directive.
+ */
 enum SMCResult
 {
 	SMCParse_Continue,			/**< Continue parsing */
@@ -32,6 +35,9 @@ enum SMCResult
 	SMCParse_HaltFail			/**< Stop parsing and return failure */
 };
 
+/**
+ * Parse error codes.
+ */
 enum SMCError
 {
 	SMCError_Okay = 0,			/**< No error */

plugins/include/usermessages.inc

@@ -18,6 +18,9 @@
 #endif
 #define _eventsmsgs_included
 
+/**
+ * UserMsg helper values.
+ */
 enum UserMsg
 {
 	INVALID_MESSAGE_ID = -1,

plugins/include/version.inc

@@ -18,8 +18,8 @@
 #endif
 #define _version_included
 
-#define SOURCEMOD_V_MAJOR		1
+#define SOURCEMOD_V_MAJOR		1				/**< SourceMod Major version */
-#define SOURCEMOD_V_MINOR		0
+#define SOURCEMOD_V_MINOR		0				/**< SourceMod Minor version */
-#define SOURCEMOD_V_RELEASE		0
+#define SOURCEMOD_V_RELEASE		0				/**< SourceMod Release version */
 
-#define SOURCEMOD_VERSION		"1.0.0.577"
+#define SOURCEMOD_VERSION		"1.0.0.577"		/**< SourceMod version string (major.minor.release.build) */