Documentation Improvements (#157)

* Documentation Improvements

* Documented slice and substr in string

doc/src/references/builtin/!Containers/array/!array.md

@@ -20,6 +20,6 @@ There is a possible confusion regarding syntax ambiguity when declaring arrays w
 
 At it's lowest level, an array is a template class, meaning it's a class that can accept a dynamic type `(array<T>)`. This concept also exists with the grid, async, and other classes in NVGT.
 
-However, Angelscript provides a convenience feature called the default array type. This allows us to choose just one template class out of all the template classes in the entire engine, and to make that 1 class much easier to declare than all the others using the bracket syntax `(T[])`, and this array class happens to be our chozen default array type in NVGT.
+However, AngelScript provides a convenience feature called the default array type. This allows us to choose just one template class out of all the template classes in the entire engine, and to make that 1 class much easier to declare than all the others using the bracket syntax `(T[])`, and this array class happens to be our chozen default array type in NVGT.
 
-Therefor, in reality `array<T>` and `T[]` do the exact same thing, it's just that the first one is the semantically correct method of declaring a templated class while the latter is a highly useful Angelscript shortcut. So now when you're looking at someone's code and you see a weird instance of `array<T>`, you can rest easy knowing that you didn't misunderstand the code and no you don't need to go learning some other crazy array type, that code author just opted to avoid using the Angelscript default array type shortcut for one reason or another.
+Therefore, in reality `array<T>` and `T[]` do the exact same thing, it's just that the first one is the semantically correct method of declaring a templated class while the latter is a highly useful AngelScript shortcut. So now when you're looking at someone's code and you see a weird instance of `array<T>`, you can rest easy knowing that you didn't misunderstand the code and no you don't need to go learning some other crazy array type, that code author just opted to avoid using the AngelScript default array type shortcut for one reason or another.

doc/src/references/builtin/!Datatypes/string/Methods/slice.nvgt

@@ -0,0 +1,19 @@
+/**
+	Extracts a substring starting at the given index and ending just before the index end (exclusive).
+	string string::slice(int start = 0, int end = 0);
+	## Arguments:
+		* int start = 0: The index where the substring begins (inclusive).
+		* int end = 0: The index where the substring ends (exclusive).
+	## Returns:
+		string: A new string with the characters modified.
+*/
+
+// Example:
+void main() {
+	string text = "Hello, world!";
+	string substring = text.slice(0, 5);
+	alert("Info", substring);
+	text = "Welcome to NVGT";
+	substring = text.slice(11, 16);
+	alert("Info", substring);
+}

doc/src/references/builtin/!Datatypes/string/Methods/substr.nvgt

@@ -0,0 +1,16 @@
+/**
+	Extracts a substring starting at the given index and containing a specific number of characters.
+	string string::substr(uint start = 0, int count = -1);
+	## Arguments:
+		* uint start = 0: The index where the substring begins (inclusive).
+		* int count = -1: The number of characters to include in the substring. -1 means all remaining characters after the start index.
+	## Returns:
+		string: A new string with the characters modified.
+*/
+
+// Example:
+void main() {
+	string text = "Hello, world!";
+	string substring = text.substr(7, 5); // Extracts "world"
+	alert("Info", substring);
+}

doc/src/references/include/Auditory User Interface (form.nvgt)/Classes/audio_form/Methods/is_disallowed_char.md

@@ -12,4 +12,4 @@ Determines whether the text of a given control contains characters that are not
 bool: true if the text of the control contains disallowed characters, false otherwise.
 
 ## Remarks:
-The `search_all` parameter will match the characters depending upon its state. If set to false, the entire string will be searched. If set to true, it will loop through each character and see if one of them contains disallowed character. Thus, you will usually set this to true. One example you might set to false is when the form only has 1 character length, but it is not required, it is looping each character already.
+The `search_all` parameter will match the characters depending upon its state. If set to false, the entire string will be searched. If set to true, it will loop through each character and see if one of them contains disallowed character. Thus, you will usually set this to true. One example you might set to false is when the form only has 1 character length, but it is not required, it is looping each character already. However, it is also a good idea to turn this off for the maximum possible performance if you're sure that the input only requires 1 length of characters.

doc/src/references/include/Auditory User Interface (form.nvgt)/Classes/audio_form/Methods/set_disallowed_chars.md

@@ -16,3 +16,5 @@ bool: true if the characters were successfully set, false otherwise.
 Setting the `use_only_disallowed_chars` parameter to true will restrict all characters that are not in the list. This is useful to prevent other characters in number inputs.
 
 Setting the chars parameter to empty will clear the characters and will switch back to default.
+
+Please note that these character sets will also restrict the text from being pasted if the clipboard contains disallowed characters.

doc/src/references/include/Auditory User Interface (form.nvgt)/Global Properties/audioform_input_disable_ralt.md

@@ -1,4 +1,4 @@
 # audioform_input_disable_ralt
-Set whether or not the right alt key should be disabled in input boxes, mostly useful for users with non-english keyboards.
+Set whether or not the right Alt key should be disabled in input boxes, mostly useful for users with non-english keyboards.
 
 `bool audioform_input_disable_ralt;`

doc/src/references/include/Character Rotation (rotation.nvgt)/!Character Rotation.md

@@ -1,5 +1,5 @@
 # character rotation
-This include contains functions for moving a rotating character in a 2d or 3d game.
+This include contains functions for moving a rotating character in a 2D or 3D game.
 
 ## Disclaimer:
-Though these have been improved over the years and though I do use this myself for Survive the Wild and my other games, it should be understood that I started writing this file in bgt when I was only 12 or 13 years old and it has only been getting improved as needed. The result is that anything from the math to the coding decisions may be less than perfect, putting it kindly. You have been warned!
+Though these have been improved over the years and though I do use this myself for Survive the Wild and my other games, it should be understood that I started writing this file in BGT when I was only 12 or 13 years old and it has only been getting improved as needed. The result is that anything from the math to the coding decisions may be less than perfect, putting it kindly. You have been warned!

doc/src/references/include/Dictionary Retrieval (dget.nvgt)/!dictionary retrieval.md

@@ -1,2 +1,2 @@
 # Dictionary retrieval functions
-The way you get values out of Angelscript dictionaries by default is fairly annoying, mainly due to its usage of out values instead of returning them. Hence this include, which attempts to simplify things.
+The way you get values out of AngelScript dictionaries by default is fairly annoying, mainly due to its usage of out values instead of returning them. Hence this include, which attempts to simplify things.

doc/src/references/include/INI Reader and Writer (ini.nvgt)/!INI Reader and Writer.md

@@ -1,4 +1,4 @@
 # INI Reader and Writer
-This is a class designed to read and write ini configuration files.
+This is a class designed to read and write INI configuration files.
 
 I can't promise that the specification will end up being followed to the letter, but I'll try. At this time, though the order of keys and sections will remain the same, the whitespace, comment, and line structure of an externally created ini file may not remain in tact if that file is updated and rewritten using this include.

doc/src/references/include/INI Reader and Writer (ini.nvgt)/classes/ini/methods/get_error_text.md

@@ -1,5 +1,5 @@
 # get_error_text
-Returns the last error message, almost always used if an ini file fails to load and you want to know why. This function also clears the error, so to figure out the line, call `ini::get_error_line()` before calling this.
+Returns the last error message, almost always used if an INI file fails to load and you want to know why. This function also clears the error, so to figure out the line, call `ini::get_error_line()` before calling this.
 
 `string ini::get_error_text();`
 

doc/src/references/include/INI Reader and Writer (ini.nvgt)/classes/ini/methods/load_string.md

@@ -1,5 +1,5 @@
 # load_string
-This function loads ini data stored as a string, doing it this way insures that ini data can come from any source, such as an encrypted string if need be.
+This function loads INI data stored as a string, doing it this way insures that ini data can come from any source, such as an encrypted string if need be.
 
 `bool ini::load_string(string data, string filename = "*");`
 

doc/src/references/include/INI Reader and Writer (ini.nvgt)/classes/ini/properties/loaded_filename.md

@@ -1,4 +1,4 @@
 # loaded_filename
-Contains the filename of the currently loaded ini data.
+Contains the filename of the currently loaded INI data.
 
 `string loaded_filename;`

doc/src/references/include/Instance Management (instance.nvgt)/!Instance Management.md

@@ -1,2 +1,2 @@
 # Instance Management
-This include provides the `instance` class, which allows you to manage the way multiple instances of your game are handled. For example, you could use use this class to check if your game is already running, or stop it from running until only one instance exists.
+This include provides the `instance` class, which allows you to manage the way multiple instances of your game are handled. For example, you could use this class to check if your game is already running, or stop it from running until only one instance exists.

doc/src/references/include/Legacy Sound Manager (sound_pool.nvgt)/Classes/sound_pool/Methods/play_stationary.md

@@ -1,5 +1,5 @@
 # play_stationary
-Play a sound without using dimension and return a slot.
+Play a stationary sound and return a slot.
 
 1. `int sound_pool::play_stationary(string filename, bool looping, bool persistent = false);`
 2. `int sound_pool::play_stationary(string filename, pack@ packfile, bool looping, bool persistent = false);`
@@ -20,3 +20,5 @@ int: the index of the sound which can be modified later, or -1 if error. This me
 
 ## Remarks:
 If the looping parameter is set to true and the sound object is inactive, the sound is still considered to be active as this just means that we are currently out of earshot. A non-looping sound that has finished playing is considered to be dead, and will be cleaned up if it is not set to be persistent.
+
+This method will play the sound in stationary mode. This means that sounds played by this method have no movement updates as if they are stationary, and coordinate update functions will not work.

doc/src/references/include/Token Generation (token_gen.nvgt)/Enums/token_gen_flag.md

@@ -6,4 +6,4 @@ This enum holds various constants that can be passed to the mode parameter of th
 * TOKEN_SYMBOLS = 4: Uses only symbols, \`\~\!\@\#\$\%\^\&\*\(\)\_\+\=\-\[\]\{\}\/\.\,\;\:\|\?\>\<
 
 ## Remarks:
-These are flags that should be combined together using the bitwise OR operator. To generate a token containing characters and symbols, for example, you would pass `TOKEN_CHARACTERS | TOKEN_NUMBERS | TOKEN_SYMBOLS` to the mode argument of generate_token. The default flags are TOKEN_CHARACTERS | TOKEN_NUMBERS.
+These are flags that should be combined together using the bitwise OR operator. To generate a token containing characters, numbers and symbols, for example, you would pass `TOKEN_CHARACTERS | TOKEN_NUMBERS | TOKEN_SYMBOLS` to the mode argument of generate_token. The default flags are `TOKEN_CHARACTERS | TOKEN_NUMBERS`.

doc/src/references/include/Token Generation (token_gen.nvgt)/Functions/!generate_token.nvgt

@@ -1,20 +1,20 @@
 /**
 	Generates a random string of characters (a token).
-	string generate_token(int token_length, int mode = token_gen_flag_all)
+	string generate_token(int token_length, int mode = TOKEN_CHARACTERS | TOKEN_NUMBERS)
 	## Arguments:
 		* int token_length: the length of the token to generate.
-		* int mode = token_gen_flag_all: allows you to specify which characters you would like in the generated token (see remarks).
+		* int mode = TOKEN_CHARACTERS | TOKEN_NUMBERS: allows you to specify which characters you would like in the generated token (see remarks).
 	## returns:
-		String: a random token depending on the mode.
+		String: a random token depending on the modes.
 	## Remarks:
-		This function uses the `generate_custom_token` function to generate. The characters used to generate the token will depend on the mode you specified. See `token_gen_flags` enum constants.
+		This function uses the `generate_custom_token` function to generate. The characters used to generate the token will depend on the modes you specified. See `token_gen_flags` enum constants for a list of supported modes that can be passed to the mode parameter.
 */
 
 // Example:
 #include "token_gen.nvgt"
 
 void main() {
 	alert("Info", "Your token is: " + generate_token(10));
-	alert("Info", "Numbers only token is: " + generate_token(10, token_gen_flag_numbers));
-	alert("Info", "Characters only token is: " + generate_token(10, token_gen_flag_characters));
+	alert("Info", "Numbers only token is: " + generate_token(10, TOKEN_NUMBERS));
+	alert("Info", "Characters only token is: " + generate_token(10, TOKEN_CHARACTERS));
 }