docs: Update code_guidance.md

docs/code_guidance.md

@@ -1,39 +1,102 @@
 Coders guidance
 add to as you see fit, but try to keep doc easy to use
 
-Useful functions:
-TTRPG_stats(faction, comp, mar, class = "marine")
-		creates a new unit struct see scr_marine_struct.gml for more info
 
-
-		unit_Struct.name_role()
-			provides a string representation of the unit name combined with the unit role 
-			taking into account the unit role display name as provided by the units squad type
-
-scr_random_marine(argument0, argument1)
-		selects a random player unit within the parameters given
-		if no marine is available with give parameters returns "none"
-
-
-keys and data:
+### keys and data:
 faction key:
 	imperium:2
 	mechanics:3
 	inquisition:4
 	sororities:5
 
-
-Visual and draw functions
-
-tooltip_draw(x,y,tooltip_text)
-	creates a hover over tool tip at the given coordinate where:
-		x is the left most point of the tooltip box
-		y is the topmost point of the tooltip box,
-		tooltip_text is the text to display (text should be preformatted e.g string_hash_to_newline() to create lines)
-
-scr_convert_company_to_string(marine company)
-	returns a sting representation of a marines compant
-How does combat work?????
+# Useful functions:
+
+## Common functions 
+Creating a Marine
+```gml
+/// @function TTRPG_stats
+/// @description creates a new unit struct see scr_marine_struct.gml for more info
+/// @param {array} rect x1, y1, x2, y2 array.
+/// @returns {bool}
+function TTRPG_stats(faction, comp, mar, class = "marine", other_spawn_data={})
+```
+Display a marine's role
+```gml
+/// provides a string representation of the unit name combined with the unit role 
+/// taking into account the unit role display name as provided by the units squad type
+unit_Struct.name_role()
+```
+Get a random marine with filter
+```gml
+/// selects a random player unit within the parameters given
+/// @param {Real|Array[Real]} role id or list of ids e.g. 2 = Honour Guard
+/// @param {Real} exp_req minimum exp requirement
+/// @param {String|Struct} search_params attributes to search for
+/// if params is a struct, can use traits or stats as part of the search
+/// if no marine is available with give parameters returns "none"
+function scr_random_marine(role, exp_req, search_params="none")
+/// @example - finding a random chaplain candidate
+random_marine=scr_random_marine([obj_ini.role[100][8],obj_ini.role[100][18],obj_ini.role[100][10],obj_ini.role[100][9]],60,{"stat":[["piety", 35, "more"],["charisma", 30, "more"]]});
+```
+
+## Visual and draw functions
+
+Click handling
+```gml
+/// @function point_and_click
+/// @description Returns true if left mouse button was clicked on the desired rectangle area.
+/// @param {array} rect x1, y1, x2, y2 array.
+/// @param {Real} cooldown how many frames/steps until another click can be registered with the same params
+/// @returns {bool} usually used as part of an if statement in a Draw handler to run code when the player clicks something like a button
+function point_and_click(rect, cooldown = 60)
+```
+Mouse Cursor Hover
+```gml
+/// @function scr_hit
+/// @description Returns true if mouse is hovering on the specified rectangle area.
+/// @returns {bool}
+function scr_hit(x1=0, y1=0, x2=0, y2=0) 
+```
+Drawing an image from file
+```gml
+/// @description Draws a png image
+/// For actual sprites with multiple frames, don't use this.
+/// @param {String} path the file path after 'images' in the 'datafiles' folder. e.g. "creation/chapters/icons"
+/// @param {Real} image_id the name of the image. Convention follows using numbers, e.g. "1.png", so that loops are useful, and it can be stored at it's own array index in the cache.
+/// @param {Real} x1 the x coordinates to start drawing
+/// @param {Real} y1 the y coordinates to start drawing
+/// @param {Real} width the width of the image
+/// @param {Real} height the height of the image
+function scr_image(path, image_id, x1, y1, width, height)
+/// @example
+scr_image("creation/chapters/icons", 1, 450, 250, 32, 32); // draws the Dark Angels chapter icon at x 450 and y 250 at size 32x32px
+```
+
+Tooltips
+```gml
+/// creates a hover over tool tip at the given coordinate where:
+/// x is the left most point of the tooltip box
+/// y is the topmost point of the tooltip box,
+/// tooltip_text is the text to display (text should be preformatted e.g string_hash_to_newline() to create lines)
+function tooltip_draw(_tooltip="", _width=350, _coords=return_mouse_consts_tooltip(), _text_color=#50a076, _font=fnt_40k_14, _header="", _header_font=fnt_40k_14b, _force_width=false){
+```
+
+Company id to string
+```gml
+/// @function scr_convert_company_to_string
+/// @description Accepts a number and adds an affix to convert it to ordinal form.
+/// @param {real} company_num Company number.
+/// @param {bool} possessive Add 's affix?
+/// @param {bool} flavour Add company designation text (Veteran, Battle, Reserve, etc.)?
+/// @returns {string}
+function scr_convert_company_to_string(company_num, possessive = false, flavour=false)
+/// @example
+scr_convert_company_to_string(1, true, true); // 1st Veteran Company
+scr_convert_company_to_string(7, true, true); // 7th Reserve Company
+```
+
+
+# How does combat work?????
 
 -  First obj_ncombat is creates.
 - second scr_battle_Roster is run with the location planet and star as arguments to collect player forces in battle