docs: clean up docstrings

Author: NathanLovato

src/field/gameboard/gameboard.gd

@@ -1,7 +1,7 @@
 ## Defines the playable area of the game and where everything on it lies.
 ##
 ## The gameboard is defined, essentially, as a grid of [Vector2i] cells. Anything may be
-## placed on one of these cells, so the gameboard determines where each cell is located. In this 
+## placed on one of these cells, so the gameboard determines where each cell is located. In this
 ## case, we are using a simple orthographic (square) projection.
 ## [br][br]The grid is contained within the playable [member boundaries] and its constituent cells.
 extends Node
@@ -12,12 +12,13 @@ signal properties_set
 
 ## Emitted whenever the [member pathfinder] state changes.
 ## This signal is emitted automatically in response to changed [GameboardLayer]s.
-##[/br][/br]Note: This signal is only emitted when the actual movement state of the Gameboard
+##
+## Note: This signal is only emitted when the actual movement state of the Gameboard
 ## changes. [GameboardLayer]s may change their cells without actually changing the pathfinder's
 ## state (i.e. a visual update only), in which case this signal is not emitted.
 signal pathfinder_changed(added_cells: Array[Vector2i], removed_cells: Array[Vector2i])
 
-## An invalid cell is not part of the gameboard. Note that this requires positive 
+## An invalid cell is not part of the gameboard. Note that this requires positive
 ## [member boundaries].
 const INVALID_CELL: = Vector2i(-1, -1)
 
@@ -43,7 +44,7 @@ func cell_to_pixel(cell_coordinates: Vector2i) -> Vector2:
 func pixel_to_cell(pixel_coordinates: Vector2) -> Vector2i:
 	@warning_ignore("integer_division")
 	return Vector2i(
-		floori(pixel_coordinates.x / properties.cell_size.x), 
+		floori(pixel_coordinates.x / properties.cell_size.x),
 		floori(pixel_coordinates.y / properties.cell_size.y)
 	)
 
@@ -73,9 +74,9 @@ func index_to_cell(index: int) -> Vector2i:
 		index % properties.extents.size.x + properties.extents.position.x,
 		index / properties.extents.size.x + properties.extents.position.y
 	)
-	
+
 	if properties.extents.has_point(cell):
-		return cell 
+		return cell
 	return INVALID_CELL
 
 
@@ -94,7 +95,7 @@ func get_adjacent_cells(cell: Vector2i) -> Array[Vector2i]:
 		var neighbour = get_adjacent_cell(cell, direction)
 		if not neighbour == INVALID_CELL and not neighbour == cell:
 			neighbours.append(neighbour)
-	
+
 	return neighbours
 
 
@@ -107,13 +108,13 @@ func register_gameboard_layer(board_map: GameboardLayer) -> void:
 	# Compare the changed cells with those already in the pathfinder. Any changes will cause the
 	# Pathfinder to be updated.
 	board_map.cells_changed.connect(
-		func _on_gameboard_layer_cells_changed(cleared_cells: Array[Vector2i], 
+		func _on_gameboard_layer_cells_changed(cleared_cells: Array[Vector2i],
 				blocked_cells: Array[Vector2i]):
 		if board_map.name == "DoorGameboardLayer":
 			print("Door layer ", cleared_cells, " ", blocked_cells)
 		var added_cells: = _add_cells_to_pathfinder(cleared_cells)
 		var removed_cells: = _remove_cells_from_pathfinder(blocked_cells)
-		
+
 		_connect_new_pathfinder_cells(added_cells)
 		if not added_cells.is_empty() or not removed_cells.is_empty():
 			pathfinder_changed.emit(added_cells.values(), removed_cells)
@@ -125,7 +126,7 @@ func register_gameboard_layer(board_map: GameboardLayer) -> void:
 # from cleared_cells). Key = cell id (int, see cell_to_index), value = coordinate (Vector2i)
 func _add_cells_to_pathfinder(cleared_cells: Array[Vector2i]) -> Dictionary[int, Vector2i]:
 	var added_cells: Dictionary[int, Vector2i] = {}
-	
+
 	# Verify whether or not cleared/blocked cells will change the state of the pathfinder.
 	# If there is no change in state, we will not pass along the cell to other systems and
 	# the pathfinder won't actually be changed.
@@ -136,15 +137,15 @@ func _add_cells_to_pathfinder(cleared_cells: Array[Vector2i]) -> Dictionary[int,
 			var uid: = cell_to_index(cell)
 			pathfinder.add_point(uid, cell)
 			added_cells[uid] = cell
-			
+
 			# Flag the cell as disabled if it is occupied.
 			if GamepieceRegistry.get_gamepiece(cell):
 				pathfinder.set_point_disabled(uid)
 	return added_cells
 
 
-# Remove cells from the pathfinder so that Gamepieces can no longer move through them. 
-# Only one Gameboard layer needs to block a cell for it to be considered blocked. 
+# Remove cells from the pathfinder so that Gamepieces can no longer move through them.
+# Only one Gameboard layer needs to block a cell for it to be considered blocked.
 # Returns an array of cell coordinates that have been blocked. Cells that were already not in the
 # pathfinder will be excluded from this array.
 func _remove_cells_from_pathfinder(blocked_cells: Array[Vector2i]) -> Array[Vector2i]:
@@ -170,23 +171,25 @@ func _connect_new_pathfinder_cells(added_cells: Dictionary[int, Vector2i]) -> vo
 					pathfinder.connect_points(uid, neighbor_id)
 
 
-# Checks all [TileMapLayers] in the [constant GameboardLayer.GROUP] to see if the cell is clear
-# (returns true) or blocked (returns false).
-# [/br][/br]A clear cell must fulfill two criteria:
-# [/br]- Exists in at least one of the [GameboardLayer]s.
-# [/br]- None of the layers block movement at this cell, as defined by the
-# [constant GameboardLayer.BLOCKED_CELL_DATA_LAYER] custom data layer (see
-# [method TileData.get_custom_data])
+## Checks all [TileMapLayers] in the [constant GameboardLayer.GROUP] to see if the cell is clear
+## (returns true) or blocked (returns false).
+##
+## A clear cell must fulfill two criteria:
+##
+## - Exists in at least one of the [GameboardLayer]s.[br]
+## - None of the layers block movement at this cell, as defined by the
+## [constant GameboardLayer.BLOCKED_CELL_DATA_LAYER] custom data layer (see
+## [method TileData.get_custom_data])
 func _is_cell_clear(coord: Vector2i) -> bool:
 	# Check to make sure that cell exists.
 	var cell_exists: = false
-	
+
 	for tilemap: GameboardLayer in get_tree().get_nodes_in_group(GameboardLayer.GROUP):
 		if tilemap and coord in tilemap.get_used_cells():
 			cell_exists = true
 			if not tilemap.is_cell_clear(coord):
 				return false
-	
+
 	# There is no terrain blocking cell movement. However we only want to allow movement if the cell
 	# actually exists in one of the tilemap layers.
 	return cell_exists

src/field/gameboard/gameboard_layer.gd

@@ -3,12 +3,14 @@
 ## Comes setup with a few tools used by designers to setup maps, specifying which cells may be
 ## moved to or from. Multiple GameboardLayers may exist simultaneously to allow developers to
 ## affect the gameboard with more than one layer.
-##[/br][/br] These collision layers may also dynamically change, with the changes being reflected
+##
+## These collision layers may also dynamically change, with the changes being reflected
 ## by the gameboard and pathfinder.
 class_name GameboardLayer extends TileMapLayer
 
 ## Emitted whenever the collision state of the tile map changes.
-##[/br][/br] The GameboardLayer's tile map may change without changing which cells are blocked or
+##
+## The GameboardLayer's tile map may change without changing which cells are blocked or
 ## are open for movement. In this case, the signal is not emitted. However, it is emitted whenever
 ## the map is added or removed from the game, in addition to when there is a change in blocked/clear
 ## cells.
@@ -19,7 +21,8 @@ const GROUP: = "GameboardTileMapLayers"
 
 ## The name of the "custom data layer" that determines whether or not a cell is blocked/walkable.
 ## The returned value will be a boolean reflecting if a cell is blocked or not. Fetches the value
-## via [method TileData.get_custom_data].[/br][/br]
+## via [method TileData.get_custom_data].
+##
 ## If the data layer is not present in the [Tileset], then all cells in this [TileMapLayer] will,
 ## by default, block movement.
 const BLOCKED_CELL_DATA_LAYER: = "IsCellBlocked"
@@ -32,11 +35,11 @@ var _affects_collision: = true
 func _ready() -> void:
 	add_to_group(GROUP)
 	Gameboard.register_gameboard_layer(self)
-	
+
 	tree_exiting.connect(
 		func _on_tree_exiting() -> void:
 			_affects_collision = false
-			
+
 			var blocked_cells: Array[Vector2i] = []
 			cells_changed.emit(get_used_cells(), blocked_cells)
 	)
@@ -53,7 +56,7 @@ func is_cell_clear(coord: Vector2i) -> bool:
 	if tile_data:
 		var is_cell_blocked: = tile_data.get_custom_data(BLOCKED_CELL_DATA_LAYER) as bool
 		return not is_cell_blocked
-	
+
 	# If the above conditions have not been met, the cell is blocked.
 	return false
 
@@ -70,18 +73,18 @@ func _update_cells(coords: Array[Vector2i], forced_cleanup: bool) -> void:
 	# layer that we need to specify whether or not a tile blocks movement.
 	if not tile_set or not tile_set.has_custom_data_layer_by_name(BLOCKED_CELL_DATA_LAYER):
 		return
-	
+
 	# Go through the specified coords, checking to see if any moveable cells (those that are NOT
 	# blocked) have been added or removed.
 	var cleared_cells: Array[Vector2i] = []
 	var blocked_cells: Array[Vector2i] = []
-	
+
 	if not forced_cleanup:
 		for coord in coords:
 			if is_cell_clear(coord):
 				cleared_cells.append(coord)
 			else:
 				blocked_cells.append(coord)
-	
+
 	if not (cleared_cells.is_empty() and blocked_cells.is_empty()):
 		cells_changed.emit(cleared_cells, blocked_cells)

src/field/gameboard/pathfinder.gd

@@ -4,9 +4,10 @@
 class_name Pathfinder
 extends AStar2D
 
-# When finding a path, we may want to ignore certain cells that are occupied by Gamepeices.
-# These flags specify which disabled cells will still allow the path through.
-## Ignore the pccupant of the source cell when searching for a path via [method path_to_cell].
+## When finding a path, we may want to ignore certain cells that are occupied by Gamepeices.
+## These flags specify which disabled cells will still allow the path through.
+##
+## Ignore the occupant of the source cell when searching for a path via [method path_to_cell].
 ## This is especially useful when wanting to find a path for a gamepiece from their current cell.
 const FLAG_ALLOW_SOURCE_OCCUPANT = 1 << 0
 ## Ignore the occupant of the target cell when searching for a path via [method path_to_cell].
@@ -23,12 +24,12 @@ func _init() -> void:
 			var new_cell_id: = Gameboard.cell_to_index(new_cell)
 			if has_point(new_cell_id):
 				set_point_disabled(new_cell_id, true)
-			
+
 			var old_cell_id: = Gameboard.cell_to_index(old_cell)
 			if has_point(old_cell_id):
 				set_point_disabled(old_cell_id, false)
 	)
-	
+
 	GamepieceRegistry.gamepiece_freed.connect(
 		func _on_gamepiece_free(_gp: Gamepiece, coord: Vector2i) -> void:
 			var cell_id: = Gameboard.cell_to_index(coord)
@@ -51,15 +52,15 @@ func can_move_to(coord: Vector2i) -> bool:
 ## Find a path between two cells. Returns an empty array if no path is available.
 ## If allow_blocked_source or allow_blocked_target are false, the pathinder wlil fail if a gamepiece
 ## occupies the source or target cells, respectively.
-func get_path_to_cell(source_coord: Vector2i, target_coord: Vector2i, 
+func get_path_to_cell(source_coord: Vector2i, target_coord: Vector2i,
 		occupancy_flags: int = 1) -> Array[Vector2i]:
 	# Store the return value in a variable.
 	var move_path: Array[Vector2i] = []
-	
+
 	# Find the source/target IDs and keep track of whether or not the cells are occupied.
 	var source_id: = Gameboard.cell_to_index(source_coord)
 	var target_id: = Gameboard.cell_to_index(target_coord)
-	
+
 	# The pathfinder has several flags to ignore cell occupancy. We'll need to track which occupants
 	# are temporarily ignored and then re-disable their pathfinder points once a path is found.
 	# Key is point id, value is whether or not the point is disabled.
@@ -69,7 +70,7 @@ func get_path_to_cell(source_coord: Vector2i, target_coord: Vector2i,
 			if is_point_disabled(id):
 				ignored_points[id] = true
 				set_point_disabled(id, false)
-	
+
 	if has_point(source_id) and has_point(target_id):
 		# Check to see if we want to un-disable the source/target cells.
 		if (occupancy_flags & FLAG_ALLOW_SOURCE_OCCUPANT) != 0:
@@ -78,15 +79,15 @@ func get_path_to_cell(source_coord: Vector2i, target_coord: Vector2i,
 		if (occupancy_flags & FLAG_ALLOW_TARGET_OCCUPANT) != 0:
 			ignored_points[target_id] = is_point_disabled(target_id)
 			set_point_disabled(target_id, false)
-		
+
 		for path_coord: Vector2i in get_point_path(source_id, target_id):
 			if path_coord != source_coord: # Don't include the source as the first path element.
 				move_path.append(path_coord)
-		
+
 		# Change any enabled cells back to their previous state.
 		for id in ignored_points:
 			set_point_disabled(id, ignored_points[id])
-	
+
 	return move_path
 
 
@@ -96,13 +97,13 @@ func get_path_cells_to_adjacent_cell(source_coord: Vector2i,
 		target_coord: Vector2i, occupancy_flags: int = 1) -> Array[Vector2i]:
 	var shortest_path: Array[Vector2i] = []
 	var shortest_path_length: = INF
-	
+
 	for cell in Gameboard.get_adjacent_cells(target_coord):
 		var cell_path: = get_path_to_cell(source_coord, cell, occupancy_flags)
 		if not cell_path.is_empty() and cell_path.size() < shortest_path_length:
 			shortest_path_length = cell_path.size()
 			shortest_path = cell_path
-	
+
 	return shortest_path
 
 
@@ -111,10 +112,10 @@ func _to_string() -> String:
 	var value: = "\nPathfinder:"
 	for index in get_point_ids():
 		var cell_header: = "\n%s - Id: %d;" % [str(Gameboard.index_to_cell(index)), index]
-		
+
 		var is_disabled: = "\t\t\t"
 		if is_point_disabled(index):
 			is_disabled = " (disabled)\t"
-			
+
 		value += (cell_header + is_disabled + "Linked to: %s" % get_point_connections(index))
 	return value + "\n"

src/field/gamepieces/gamepiece.gd

@@ -52,7 +52,8 @@ signal direction_changed(new_direction: Directions.Points)
 			follower.add_child(animation)
 
 ## The gamepiece will traverse a movement path at [code]move_speed[/code] pixels per second.
-##[/br][/br]Note that extremely high speeds (finish a long path in a single frame) will produce
+##
+## Note that extremely high speeds (finish a long path in a single frame) will produce
 ## unexpected results.
 @export var move_speed: = 64.0
 
@@ -88,7 +89,8 @@ var destination: Vector2
 
 ## Node2Ds may want to follow the gamepiece's animation, rather than position (which updates only at
 ## the end of a path). Nodes may follow a travelling gamepiece by receiving the path follower's
-## transform.[/br][/br]
+## transform.
+##
 ## The [member RemoteTransform2D.remote_path] is reserved for the player camera, but other nodes
 ## may access the anchor's position directly.
 @onready var animation_transform: = $PathFollow2D/CameraAnchor as RemoteTransform2D

src/field/gamepieces/gamepiece_registry.gd

@@ -3,8 +3,9 @@
 ## Since player movement is locked to gameboard cells (rather than physics-based movement), this
 ## allows UI elements, cutscenes, and other systems to quickly lookup gamepieces by name or
 ## location. Additionally, it allows pathfinders to see which cells are occupied or unoccupied.
-## [/br][/br]Note that only ONE gamepiece may occupy a cell and will block the movement of other
-## gamepieces. 
+##
+## Note that only ONE gamepiece may occupy a cell and will block the movement of other
+## gamepieces.
 extends Node
 
 signal gamepiece_moved(gp: Gamepiece, new_cell: Vector2i, old_cell: Vector2i)
@@ -20,20 +21,20 @@ func register(gamepiece: Gamepiece, cell: Vector2i) -> bool:
 		printerr("Failed to register Gamepiece '%s' at cell '%s'. " % [gamepiece.name, str(cell)],
 			"A gamepiece already exists at that cell!")
 		return false
-	
+
 	#...or if it has already been registered, for some reason.
 	if gamepiece in _gamepieces.values():
 		printerr("Refused to register Gamepiece '%s' at cell '%s'. " % [gamepiece.name, str(cell)],
 			"The gamepiece has already been registered!")
 		return true
-	
+
 	# We want to know when the gamepiece leaves the scene tree, as it is no longer on the gameboard.
 	# This probably means that the gamepiece has been freed.
 	gamepiece.tree_exiting.connect(_on_gamepiece_tree_exiting.bind(gamepiece))
-	
+
 	_gamepieces[cell] = gamepiece
 	gamepiece_moved.emit(gamepiece, cell, Gameboard.INVALID_CELL)
-	
+
 	return true
 
 
@@ -45,14 +46,14 @@ func move_gamepiece(gp: Gamepiece, new_cell: Vector2i) -> bool:
 	if _gamepieces.has(new_cell):
 		print("Cell %s is already occupied, cannot move gamepiece '%s'!" % [str(new_cell), gp.name])
 		return false
-	
+
 	var old_cell: = get_cell(gp)
 	if old_cell == new_cell:
 		return false
-	
+
 	_gamepieces.erase(old_cell)
 	_gamepieces[new_cell] = gp
-	
+
 	gamepiece_moved.emit(gp, new_cell, old_cell)
 	return true
 
@@ -94,7 +95,7 @@ func _on_gamepiece_tree_exiting(gp: Gamepiece) -> void:
 	if _gamepieces.has(cell):
 		_gamepieces.erase(cell)
 		gamepiece_freed.emit(gp, cell)
-	
+
 	#if cell != null:
 		#Events.gamepiece_exiting_tree.emit(gp, cell)