Update lang.inc

plugins/include/lang.inc

@@ -16,19 +16,43 @@
 #endif
 #define _lang_included
 
-//return the number of languages loaded
+/**
+ * Returns the number of languages loaded.
+ *
+ * @return 			Number of languages loaded.		
+ */
 native get_langsnum();
 
-//sets name to the two-letter name of a language returned by get_langsnum
+/**
-//index starts at 0
+ * Returns the two-letter name of a language returned by get_langsnum()
+ *
+ * @param id		Language index, starting at 0
+ * @param name 		Buffer to store the name in
+ *
+ * @noreturn
+ */
 native get_lang(id, name[3]);
 
-//registers a dictionary file, making sure the words are in the dictionary
+/**
-// the file should be in "addons/amxx/data/lang/", but only the name needs to be
+ * Registers a dictionary file, making sure the words are in the dictionary.
-// given.  (e.g. register_dictionary("file.txt") will be addons/amxx/data/file.txt).
+ *
+ * @note The file should be in "addons/amxmodx/data/lang", but only the name
+ *		 needs to be given. For example, register_dictionary("file.txt") will
+ *		 be "addons/amxmodx/data/lang/file.txt".
+ *
+ * @param filename	Dictionary file name
+ *
+ * @return 			On success, the function will return 1, otherwise it will
+ *					return 0 if the file couldn't be found or opened, and -1 if
+ *					the dictionary was already registered by a plugin
+ */
 native register_dictionary(const filename[]);
 
-//returns 1 if the language is loaded, 0 otherwise.
+/**
+ * Checks if the language is loaded.
+ *
+ * @return 			1 if it is, 0 otherwise
+ */
 native lang_exists(const name[]);
 
 enum TransKey
@@ -37,27 +61,52 @@ enum TransKey
 };
 
 /**
- * Adds or finds a translation key.
+ * Creates a new or finds an existing translation key.
+ *
+ * @param key		Key to create or find
+ *
+ * @return			Key index
  */
 native TransKey:CreateLangKey(const key[]);
 
 /**
- * Finds a translation key id without adding on failure.
+ * 
  * Returns -1 on not found.
  */
+ 
+/**
+ * Finds a translation key index without adding on failure.
+ *
+ * @param key		Key to search for
+ *
+ * @return			Key index, or -1 if not found
+ */
 native TransKey:GetLangTransKey(const key[]);
  
 /**
- * Adds a translation.
+ * Adds a new translation.
+ *
+ * @param lang		Two-letter language name
+ * @param key		Language key
+ * @param phrase	Translated text
+ *
+ * @noreturn
  */
 native AddTranslation(const lang[3], TransKey:key, const phrase[]);
 
 /**
- * Looks up the translation of the key for the given type
+ * Looks up the translation of the key for the given type.
- * This does NOT format the output text.
+ *
- * eg: If the key includes %s, the outputted text will also contain %s.
+ * @note This does NOT format the output text! For example, if the key
- * NOTE: LANG_PLAYER is invalid in this, use a player index
+ * 		 contains %s, the outputted text will also contain %s.
- *       or LANG_SERVER
+ * @note LANG_PLAYER is invalid in this, use a player index or LANG_SERVER.
+ *
+ * @param Output		Buffer to store the output in
+ * @param OutputSize	Maximum buffer size
+ * @param Key		 	Language key
+ * @param id		 	Client index or LANG_SERVER
+ *
+ * @return 				1 on success, 0 otherwise
  */
 native LookupLangKey(Output[], OutputSize, const Key[], &id);