Code documentation (#91)

* Comment most of the codebase (except stuff related to animations and map UI)

#Scenes/TestingScene.tscn

@@ -1,7 +1,7 @@
 [gd_scene load_steps=18 format=3 uid="uid://b60uabg68ra1l"]
 
 [ext_resource type="Script" path="res://#Scenes/SceneScripts/TestingScene.gd" id="1_ji0t8"]
-[ext_resource type="Script" path="res://Map/MapManager.gd" id="2_50npk"]
+[ext_resource type="Script" path="res://Managers/MapManager.gd" id="2_50npk"]
 [ext_resource type="PackedScene" uid="uid://clmg3l3n28x38" path="res://Entity/Player/Player.tscn" id="3_4psp7"]
 [ext_resource type="PackedScene" uid="uid://dpjfy4pv0vxst" path="res://Cards/CardContainer.tscn" id="3_e7sws"]
 [ext_resource type="Script" path="res://#Scenes/SceneScripts/TestingScene_UIcontrol.gd" id="4_h8431"]

CONTRIBUTING.md

@@ -1,3 +1,12 @@
+# Table of contents
+
+- [Contributing : how to ?](#contributing--how-to-)
+ - [Commits](#commits)
+ - [Pull requests](#pull-requests)
+- [Tests](#tests)
+- [Code formatting](#code-formatting)
+- [Documentation](#documentation)
+
 # Contributing : how to ?
 
 If you want to help with code, first check that there is no issue already opened about the thing you want to work on. 
@@ -24,11 +33,11 @@ Here is a (non exhaustive) list of reasons for which your pull request can be cl
 
 If you are the last one to approve a pull request, there are no unresolved conversations and the tests are passing, you can merge the pull request yourself.
 
-## Tests
+# Tests
 
 If you are writing code that implements something new, please provide test files written in GDScript (that can be run on GUT), as they will be useful to test future PR. If you do not know what to write tests on, don't hesitate to ask.
 
-## Code formatting
+# Code formatting
 
 As of the writing of this CONTRIBUTING.md there is no code formatter for Godot, even though it might come later. Try to follow the code conventions of the [GDScript style guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html)
 
@@ -39,3 +48,8 @@ As of the writing of this CONTRIBUTING.md there is no code formatter for Godot,
 - Write the parent class name as SomethingBase (for example, the base of the cards is `CardBase`)
 - If you have C child of B and B child of A, B should not follow the previous convention, only A should. This rule may have exceptions.
 - Writing multiple smaller lines is better than writing one big line.
+
+# Documentation
+
+Always write documentation for your code. Check how it's done in other files if you don't know how to write it. Check [Godot's page about documentation](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_documentation_comments.html) comments for syntax related information.
+Code inside functions should also be commented (but using normal comments, not documentation comments). This doesn't exempt you from using explicit variable names and function names.

Cards/CardBase.gd

@@ -4,43 +4,56 @@ class_name CardBase
 ## use if they want.
 ##
 ## The intention with this is to provide functionality that is common to a lot of cards,
-## like dealing damage, drawing cards, and restoring resources.
+## like dealing damage, drawing cards, and restoring resources.[br]
 ## If you want functionality that's unique to a certain card, then create a new child of this
-## and override one of the functions below.
+## and override one of the functions below.[br]
 ## This resource also has data that is used for displaying the card in the world, like
-## description, title, and key art.
+## description, title, and key art.[br]
 ## This includes functionality for applying damage to both the target and caster. Casters may
-## wish to take damage in some contexts.
+## wish to take damage in some contexts.[br]
 ## For example, consider the card: "Deal 10 damage to all enemies, but take 3 damage"
 
+## Define the type of entity this card can be played on [br]
+## Possible values: see [enum GlobalEnums.ApplicationType]
 @export var application_type: GlobalEnums.ApplicationType = GlobalEnums.ApplicationType.ENEMY_ONLY
+
+## The name of the card
 @export var card_title: String = "NULL"
+
+## The art used on the card (ie the image at the top, not the layout of the card)
 @export var card_key_art: ImageTexture = null
+
+## The description of the card
 @export var card_description: String = "NULL"
 
+## A list of the effects that the card will apply when played [br]
+## Effect data is not purely the effect, it also contains information about targets among other things, see [EffectData]
 @export var card_effects_data: Array[EffectData] = []
 
+## How much energy is needed to play this card
 @export var energy_info: EnergyData = EnergyData.new()
 
+## Used to check the order in which effects and related animations are played
 var _card_effects_queue: Array[EffectData] = []
+
+## Used to check which targets have been hit by an effect [br]
+## TODO this needs better phrasing
 var _targets_triggered_hits: Array[Entity] = []
 
+
+# ? is this actually needed anymore
+## Called when the node enters the scene tree for the first time.
 func _ready() -> void:
  card_effects_data = []
 
-# Need a parser of some sort to read a plainform card data and translate it to EffectData
-# This will call EffectData.add_effect_data() in a loop for every new effect
-
-@warning_ignore("unused_parameter")
-func parse_card_data(card_data: Dictionary) -> void:
- # TODO
- pass
-
-
+## Check if the caster can play the card on the target. This is different from checking if the player has enough energy. [br]
+## Instead it checks if the application type of the card is compatible with the target (cannot play a card with an effect on enemies on yourself for example)
 func can_play_card(caster: Entity, target: Entity) -> bool:
  return caster.get_party_component().can_play_on_entity(application_type, target)
 
 
+## To be linked with a signal to activate this function. [br]
+## Applies all the effects of the cards to the listed targets.
 func on_card_play(caster: Entity, base_target: Entity) -> void:
  if caster is Player:
  PlayerManager.player.get_energy_component().use_energy(self) 
@@ -53,6 +66,7 @@ func on_card_play(caster: Entity, base_target: Entity) -> void:
  _handle_effects_queue(caster, base_target)
 
 
+## Applies effects of the card sequentially, to ensure proper animation display
 func _handle_effects_queue(caster: Entity, base_target: Entity) -> void:
  var card_effect: EffectData = _card_effects_queue[0]
  var animation_data: CastAnimationData = card_effect.animation_data
@@ -92,6 +106,9 @@ func _handle_effects_queue(caster: Entity, base_target: Entity) -> void:
  CardManager.on_card_action_finished.emit(self)
 
 
+## Check whether or not a target has already been hit by an effect or not [br]
+## @experimental
+## This might change later for effects that can target the same entity multiple times
 func animation_hit(hit_target: Entity, card_effect: EffectData, caster: Entity) -> void:
  if _targets_triggered_hits.has(hit_target):
  push_error("Hit was triggered on " + hit_target.name + " more than once! Skipping effects")

Cards/CardContainer.tscn

@@ -3,7 +3,7 @@
 [ext_resource type="Script" path="res://Cards/CardContainer.gd" id="1_8wctf"]
 [ext_resource type="PackedScene" uid="uid://caxbd2ppk3ans" path="res://Cards/Card.tscn" id="2_ytmtr"]
 [ext_resource type="Resource" uid="uid://dxgoopi1roxu4" path="res://Cards/Resource/Card_Damage.tres" id="3_bi3df"]
-[ext_resource type="Resource" uid="uid://0x385c3nuq8f" path="res://Cards/Resource/Card_DamageAll.tres" id="4_14cb3"]
+[ext_resource type="Resource" uid="uid://0x385c3nuq8f" path="res://Cards/Resource/Card_DamageAllEnemies.tres" id="4_14cb3"]
 [ext_resource type="Resource" uid="uid://boodcfdepyk5i" path="res://Cards/Resource/Card_DamageHealth.tres" id="5_dugjd"]
 [ext_resource type="Resource" uid="uid://d4lugn62mmlep" path="res://Cards/Resource/Card_DrawCards.tres" id="6_56fxe"]
 [ext_resource type="Resource" uid="uid://d12g33rc6c3u5" path="res://Cards/Resource/Card_Heal.tres" id="7_6wjqi"]

Cards/CardSets/DefaultDeck.tres

@@ -1,9 +1,9 @@
-[gd_resource type="Resource" script_class="CardSetBase" load_steps=17 format=3 uid="uid://cda81lacxt2ai"]
+[gd_resource type="Resource" script_class="CardSetBase" load_steps=18 format=3 uid="uid://cda81lacxt2ai"]
 
 [ext_resource type="Script" path="res://Cards/CardSetBase.gd" id="1_pnxc0"]
 [ext_resource type="Resource" uid="uid://dam752rc15nu5" path="res://Cards/Resource/Card_Buff_Poison_Duration.tres" id="1_to4gc"]
 [ext_resource type="Resource" uid="uid://dxgoopi1roxu4" path="res://Cards/Resource/Card_Damage.tres" id="2_q7qqo"]
-[ext_resource type="Resource" uid="uid://0x385c3nuq8f" path="res://Cards/Resource/Card_DamageAll.tres" id="3_pvtk1"]
+[ext_resource type="Resource" uid="uid://0x385c3nuq8f" path="res://Cards/Resource/Card_DamageAllEnemies.tres" id="3_v5ynn"]
 [ext_resource type="Resource" uid="uid://boodcfdepyk5i" path="res://Cards/Resource/Card_DamageHealth.tres" id="4_es3ma"]
 [ext_resource type="Resource" uid="uid://3s4aet1ciesh" path="res://Cards/Resource/Card_damage_and_poison.tres" id="5_giy28"]
 [ext_resource type="Resource" uid="uid://uv2rili0xf3x" path="res://Cards/Resource/Card_Damage_EVERYTHING.tres" id="6_gr534"]
@@ -13,10 +13,11 @@
 [ext_resource type="Resource" uid="uid://btj36bhn3n2tr" path="res://Cards/Resource/Card_Strength.tres" id="10_7m46u"]
 [ext_resource type="Resource" uid="uid://b4kmg3lm0e45q" path="res://Cards/Resource/Card_Vulnerability.tres" id="11_0eivv"]
 [ext_resource type="Resource" uid="uid://bobfsmcwcgsbb" path="res://Cards/Resource/Card_Weakness.tres" id="12_lo5f6"]
-[ext_resource type="Resource" uid="uid://dans622owjixj" path="res://Cards/Resource/Card_Slap.tres" id="13_icpmb"]
-[ext_resource type="Resource" uid="uid://vydmm1p103mg" path="res://Cards/Resource/Card_FaunaSweep.tres" id="14_6fjmx"]
-[ext_resource type="Resource" uid="uid://yc2ns5s0qask" path="res://Cards/Resource/Card_SuperSlap.tres" id="15_03xhy"]
+[ext_resource type="Resource" uid="uid://c4nm7mbdlsf6r" path="res://Cards/Resource/Card_Banana.tres" id="13_v3qs7"]
+[ext_resource type="Resource" uid="uid://vydmm1p103mg" path="res://Cards/Resource/Card_FaunaSweep.tres" id="14_ghttq"]
+[ext_resource type="Resource" uid="uid://dans622owjixj" path="res://Cards/Resource/Card_Slap.tres" id="15_ie3pe"]
+[ext_resource type="Resource" uid="uid://yc2ns5s0qask" path="res://Cards/Resource/Card_SuperSlap.tres" id="16_jluts"]
 
 [resource]
 script = ExtResource("1_pnxc0")
-card_set = Array[Resource("res://Cards/CardBase.gd")]([ExtResource("1_to4gc"), ExtResource("2_q7qqo"), ExtResource("3_pvtk1"), ExtResource("4_es3ma"), ExtResource("5_giy28"), ExtResource("6_gr534"), ExtResource("7_y1gya"), ExtResource("8_haia1"), ExtResource("9_1tkbv"), ExtResource("10_7m46u"), ExtResource("11_0eivv"), ExtResource("12_lo5f6"), ExtResource("13_icpmb"), ExtResource("14_6fjmx"), ExtResource("15_03xhy")])
+card_set = Array[Resource("res://Cards/CardBase.gd")]([ExtResource("1_to4gc"), ExtResource("2_q7qqo"), ExtResource("3_v5ynn"), ExtResource("4_es3ma"), ExtResource("5_giy28"), ExtResource("6_gr534"), ExtResource("7_y1gya"), ExtResource("8_haia1"), ExtResource("9_1tkbv"), ExtResource("10_7m46u"), ExtResource("11_0eivv"), ExtResource("12_lo5f6"), ExtResource("13_v3qs7"), ExtResource("14_ghttq"), ExtResource("15_ie3pe"), ExtResource("16_jluts")])

Cards/Effects/EffectAddEnergy.gd

@@ -1,5 +1,9 @@
 class_name EffectAddEnergy extends EffectBase
+## Add energy to the player
+##
+## Refer to [EnergyComponent] for more information.
 
-# @overide
+## @Override [br]
+## Refer to [EffectBase]
 func apply_effect(_caster: Entity, _target: Entity, value: int) -> void:
  PlayerManager.player.get_energy_component().add_energy(value)

Cards/Effects/EffectApplyStatus.gd

@@ -1,8 +1,14 @@
 class_name EffectApplyStatus extends EffectBase
+## Apply a status to the target entity
+##
+## This class is useful to not have one effect per Status to apply (which was the case before). [br]
+## Refer to [StatusBase] and [StatusComponent] for more information about statuses.
 
+## The status to apply
 @export var status_to_apply: StatusBase
 
-# @Override
+## @Override [br]
+## Refer to [EffectBase]
 @warning_ignore("unused_parameter")
 func apply_effect(caster: Entity, target: Entity, value: int) -> void:
  target.get_status_component().add_status(status_to_apply, caster)

Cards/Effects/EffectBase.gd

@@ -1,6 +1,19 @@
-# Base class for card effects
 class_name EffectBase extends Resource
+## The parent class of all effects
+##
+## An effect is the smallest unit of action that can be done in the game. [br]
+## It is a simple action that can be applied to an entity.
+## For example, dealing damage, healing, drawing cards... [br]
+## Some effects don't do anything on their own and need something more (see [EffectApplyStatus] which applies a status). [br]
+## Cards have one or more effects that are applied when the card is played.
 
+
+## Apply the effect to the target entity [br]
+## [param caster] The entity that is applying the effect [br]
+## [param target] The entity that is the target of the effect [br]
+## [param value] A numerical value to quantify the strength of the effect [br]
+## The [param caster] and [param target] parameters are used to determine the modification of the [param value] due to the entities' stats (usually modified via Status) [br]
+## Refer to [EntityStats] and the related effects to see how this calculation is done. [br]
 @warning_ignore("unused_parameter")
 func apply_effect(caster: Entity, target: Entity, value: int) -> void:
  pass

Cards/Effects/EffectDamage.gd

@@ -1,6 +1,11 @@
 class_name EffectDamage extends EffectBase
+## Deal damage to an entity. [br]
+##
+## This effect will deal damage to the target entity. The damage is calculated based on the value of the effect, the caster and target stats. [br]
+## Modifier key is DAMAGE. [br]
 
-# @Override
+## @Override [br]
+## Refer to [EffectBase]
 func apply_effect(caster: Entity, target: Entity, value: int) -> void:
  # calculate modified damage given caster and target stats
  var damage: float = EntityStats.get_value_modified_by_stats(GlobalEnums.PossibleModifierNames.DAMAGE, caster, target, value)

Cards/Effects/EffectDamageHealth.gd

@@ -1,6 +1,11 @@
 class_name EffectDamageHealth extends EffectDamage
+## Deal damage to target equal to amount of health lost by caster (up to max health). [br]
+##
+## @experimental [br]
+## This is not to be used in the real game but is more meant as a testing tool. [br]
 
-# @Override
+## @Override [br]
+## Refer to [EffectBase]
 @warning_ignore("unused_parameter")
 func apply_effect(caster: Entity, target: Entity, value: int) -> void:
  var _amount_of_health_lost: int = 0

Cards/Effects/EffectData.gd

@@ -1,10 +1,15 @@
 class_name EffectData extends Resource
+## Wrapper around the effect class to store the data of the effect
+##
+## This is a convenient way to apply effect while holding all the necessary information in a single class.
 
-# Effect data is a wrapper for the Effect class. It contains an effect, a caster, a target and a value (which will be applied by the effect)
-
+## The effect to apply
 @export var effect: EffectBase = null
+## The entity that cast the effect (depends on the context).
 var caster: Entity = null
+## The value of the effect, see [EffectBase] for more information.
 @export var value: int = 0
+## The targeting function to use. This will give the list of all the targets that the effect is cast on, see [TargetingBase] for more information.
 @export var targeting_function: TargetingBase = null
 @export var animation_data: CastAnimationData = null
 
@@ -21,6 +26,6 @@ func _init(
  self.targeting_function = _targeting_function
  self.animation_data = _animation_data
 
+## Help function to call more easily from the card point of view
 func apply_effect_data(_caster: Entity = caster, target: Entity = null) -> void:
- # Help function to call more easily from the card point of view
  self.effect.apply_effect(_caster, target, self.value)

Cards/Effects/EffectDiscardRandom.gd

@@ -1,6 +1,10 @@
 class_name EffectDiscardRandom extends EffectBase
+## Discard a random card from the player's hand.
+##
+## This is often used as a penalty effect / side effect of a powerful card.
 
-# @Override
+## @Override [br]
+## Refer to [EffectBase]
 @warning_ignore("unused_parameter")
 func apply_effect(caster: Entity, target: Entity, value: int) -> void:
  CardManager.card_container.discard_random_card(value)

Cards/Effects/EffectDraw.gd

@@ -1,6 +1,14 @@
 class_name EffectDraw extends EffectBase
+## Draw one or more cards from the draw pile. [br]
+##
+## The value of the effect is the number of cards to draw. [br]
+## If there are not enough cards in the draw pile, the effect will draw as many cards as possible. [br]
+## The discard pile will then be shuffled into the draw pile, and the remaining cards will be drawn. [br]
+## This continues until either all the cards are drawn, or the player hand is full. [br]
+## Refer to [param max_hand_size] in [CardContainer] for the maximum number of cards that can be held in the player hand. [br]
 
-# @Override
+## @Override [br]
+## Refer to [EffectBase]
 func apply_effect(caster: Entity, target: Entity, value: int) -> void:
  var modified_value: int = EntityStats.get_value_modified_by_stats(GlobalEnums.PossibleModifierNames.DRAW, caster, target, value)
  CardManager.card_container.draw_cards(modified_value)

Cards/EnergyData.gd

@@ -1,4 +1,10 @@
 extends Resource
 class_name EnergyData
+## Defines how much energy is needed to perform an action
+##
+## This is mainly used for cards for now, but it could be used for other things. [br]
+## It also only contains an energy cost for now. Having its own class helps with typing and organization, instead of just using an int.
 
+
+## The energy cost of the action [br]
 @export var energy_cost: int = 0

Cards/Resource/Card_Banana.tres

@@ -34,5 +34,5 @@ animation_data = SubResource("Resource_uhx7l")
 script = ExtResource("7_wyv0k")
 application_type = 1
 card_title = "Throw Banana"
-card_description = "Deals 5 damage to all targets."
+card_description = "Deals 5 damage to all enemies."
 card_effects_data = Array[ExtResource("5_gk4p6")]([SubResource("Resource_5b3is")])

Cards/Resource/Card_Buff_Poison_Duration.tres

@@ -1,4 +1,4 @@
-[gd_resource type="Resource" script_class="CardBase" load_steps=12 format=3 uid="uid://dam752rc15nu5"]
+[gd_resource type="Resource" script_class="CardBase" load_steps=14 format=3 uid="uid://dam752rc15nu5"]
 
 [ext_resource type="Script" path="res://Cards/Effects/EffectApplyStatus.gd" id="1_2mdel"]
 [ext_resource type="Script" path="res://Status/Buffs/Buff_Poison_Duration.gd" id="2_3gm2g"]

Cards/Resource/Card_DamageAll.tres → Cards/Resource/Card_DamageAllEnemies.tres

@@ -1,31 +1,31 @@
 [gd_resource type="Resource" script_class="CardBase" load_steps=10 format=3 uid="uid://0x385c3nuq8f"]
 
-[ext_resource type="Script" path="res://Cards/CardBase.gd" id="1_j02oq"]
-[ext_resource type="Script" path="res://Cards/Effects/EffectDamage.gd" id="1_ktww3"]
-[ext_resource type="Script" path="res://Cards/Effects/EffectData.gd" id="2_ar7ey"]
-[ext_resource type="Script" path="res://Cards/EnergyData.gd" id="3_fws2c"]
-[ext_resource type="Script" path="res://Cards/Targeting/TargetAllEnemies.gd" id="3_qkswr"]
+[ext_resource type="Script" path="res://Cards/Effects/EffectDamage.gd" id="1_fpg0t"]
+[ext_resource type="Script" path="res://Cards/Effects/EffectData.gd" id="2_ib0yg"]
+[ext_resource type="Script" path="res://Cards/Targeting/TargetAllEnemies.gd" id="3_rqas5"]
+[ext_resource type="Script" path="res://Cards/EnergyData.gd" id="4_yc1ma"]
+[ext_resource type="Script" path="res://Cards/CardBase.gd" id="5_cj041"]
 
 [sub_resource type="Resource" id="Resource_f6djy"]
-script = ExtResource("1_ktww3")
+script = ExtResource("1_fpg0t")
 
 [sub_resource type="Resource" id="Resource_4lyyh"]
-script = ExtResource("3_qkswr")
+script = ExtResource("3_rqas5")
 
 [sub_resource type="Resource" id="Resource_cwhuj"]
-script = ExtResource("2_ar7ey")
+script = ExtResource("2_ib0yg")
 effect = SubResource("Resource_f6djy")
 value = 2
 targeting_function = SubResource("Resource_4lyyh")
 
 [sub_resource type="Resource" id="Resource_noiey"]
-script = ExtResource("3_fws2c")
+script = ExtResource("4_yc1ma")
 energy_cost = 1
 
 [resource]
-script = ExtResource("1_j02oq")
+script = ExtResource("5_cj041")
 application_type = 1
 card_title = "Damage All"
 card_description = "Deal 2 to all enemies"
-card_effects_data = Array[ExtResource("2_ar7ey")]([SubResource("Resource_cwhuj")])
+card_effects_data = Array[ExtResource("2_ib0yg")]([SubResource("Resource_cwhuj")])
 energy_info = SubResource("Resource_noiey")