Documentation fixes

Author: shoyguer

addons/SmoothScroll/helpers/scroll_debugger.gd

@@ -9,16 +9,16 @@ extends RefCounted
 static var debug_gradient: Gradient = null
 
 
-## Sets up the gradient for debug visualization
+## Sets up the gradient for debug visualization.
 static func setup_debug_drawing() -> void:
 	if debug_gradient == null:
 		debug_gradient = Gradient.new()
 		debug_gradient.set_color(0.0, Color.GREEN)
 		debug_gradient.set_color(1.0, Color.RED)
 
 
-## Draws debug visualization showing overdrag distances and velocity.
-## [param container] - The SmoothScrollContainer to draw debug info for
+## Draws debug visualization for the specified [param container]. [br]
+## Shows overdrag distances and velocity indicators using colored lines.
 static func draw_debug(container: SmoothScrollContainer) -> void:
 	if not container.content_node: return
 

addons/SmoothScroll/helpers/scroll_input_handler.gd

@@ -33,14 +33,13 @@ var drag_temp_data: Array = []
 #endregion
 
 
-## Initializes the input handler with a container reference.
-## [param container] - The SmoothScrollContainer to handle input for
+## Initializes the input handler with a reference to the [param container].
 func _init(container: SmoothScrollContainer) -> void:
 	_container = container
 
 
-## Processes GUI input events for scrolling.
-## [param event] - The input event to process
+## Processes GUI input events for scrolling. [br]
+## Handles mouse wheel, dragging, pan gestures, and touch events from [param event].
 func process_gui_input(event: InputEvent) -> void:
 	# Show scrollbars on mouse motion
 	if _container.hide_scrollbar_over_time and event is InputEventMouseMotion:
@@ -68,9 +67,8 @@ func process_gui_input(event: InputEvent) -> void:
 		_container.get_tree().get_root().set_input_as_handled()
 
 
-## Processes scrollbar input events.
-## [param event] - The input event to process
-## [param vertical] - True for vertical scrollbar, false for horizontal
+## Processes scrollbar input events from [param event]. [br]
+## Handles both [param vertical] and horizontal scrollbar interactions.
 func process_scrollbar_input(event: InputEvent, vertical: bool) -> void:
 	if event is InputEventMouseButton:
 		# Forward wheel events to main input handler
@@ -90,8 +88,7 @@ func process_scrollbar_input(event: InputEvent, vertical: bool) -> void:
 		_handle_scrollbar_touch(event, vertical)
 
 
-## Called when mouse enters/exits scrollbar area.
-## [param entered] - True if mouse entered, false if exited
+## Called when mouse enters or exits scrollbar area based on [param entered].
 func on_mouse_scrollbar(entered: bool) -> void:
 	mouse_on_scrollbar = entered
 
@@ -101,7 +98,7 @@ func any_scrollbar_dragging() -> bool:
 	return h_scrollbar_dragging or v_scrollbar_dragging
 
 
-## Initializes drag temporary data with current position and boundaries.
+## Initializes drag temporary data with current position and boundary distances.
 func init_drag_temp_data() -> void:
 	var spare_size: Vector2 = ScrollLayout.get_spare_size(_container, _container.content_margins)
 	var content_node_size_diff: Vector2 = ScrollLayout.get_child_size_diff(
@@ -126,8 +123,7 @@ func init_drag_temp_data() -> void:
 	]
 
 
-## Processes mouse button events (wheel scrolling and drag).
-## [param event] - The mouse button event
+## Processes mouse button events for wheel scrolling and dragging from [param event].
 func _process_mouse_button(event: InputEventMouseButton) -> void:
 	match event.button_index:
 		MOUSE_BUTTON_WHEEL_DOWN:
@@ -149,10 +145,8 @@ func _process_mouse_button(event: InputEventMouseButton) -> void:
 				_end_content_drag()
 
 
-## Handles mouse wheel scrolling.
-## [param event] - The mouse button event
-## [param positive] - True for positive direction (up/left), false for negative (down/right)
-## [param is_vertical] - True for vertical wheel, false for horizontal wheel
+## Handles mouse wheel scrolling from [param event]. [br]
+## Scrolls in [param positive] direction (up/left or down/right) for the specified axis ([param is_vertical]).
 func _handle_wheel_scroll(event: InputEventMouseButton, positive: bool, is_vertical: bool) -> void:
 	_container.last_scroll_type = SmoothScrollContainer.SCROLL_TYPE.WHEEL
 	_container.scroll_damper = _container.wheel_scroll_damper
@@ -195,8 +189,7 @@ func _end_content_drag() -> void:
 	is_in_deadzone = false
 
 
-## Processes drag motion events.
-## [param event] - The motion event with relative movement
+## Processes drag motion events with relative movement from [param event].
 func _process_drag_motion(event) -> void:
 	if not content_dragging: return
 
@@ -209,8 +202,7 @@ func _process_drag_motion(event) -> void:
 	_container.handle_content_dragging()
 
 
-## Processes pan gesture events.
-## [param event] - The pan gesture event
+## Processes pan gesture events from [param event].
 func _process_pan_gesture(event: InputEventPanGesture) -> void:
 	if _container.should_scroll_horizontal():
 		_container.velocity.x = -event.delta.x * speed
@@ -220,8 +212,7 @@ func _process_pan_gesture(event: InputEventPanGesture) -> void:
 		_container.scrollbar_animator.kill_scroll_tweens()
 
 
-## Processes screen touch events.
-## [param event] - The touch event
+## Processes screen touch events from [param event].
 func _process_screen_touch(event: InputEventScreenTouch) -> void:
 	if event.pressed:
 		if not drag_with_touch:
@@ -238,9 +229,8 @@ func _process_screen_touch(event: InputEventScreenTouch) -> void:
 		is_in_deadzone = false
 
 
-## Handles scrollbar dragging with mouse button.
-## [param event] - The mouse button event
-## [param vertical] - True for vertical scrollbar, false for horizontal
+## Handles scrollbar dragging with mouse button from [param event]. [br]
+## Processes [param vertical] or horizontal scrollbar interactions.
 func _handle_scrollbar_drag_button(event: InputEventMouseButton, vertical: bool) -> void:
 	if event.pressed:
 		if vertical:
@@ -256,9 +246,8 @@ func _handle_scrollbar_drag_button(event: InputEventMouseButton, vertical: bool)
 			h_scrollbar_dragging = false
 
 
-## Handles scrollbar dragging with touch.
-## [param event] - The touch event
-## [param vertical] - True for vertical scrollbar, false for horizontal
+## Handles scrollbar dragging with touch from [param event]. [br]
+## Processes [param vertical] or horizontal scrollbar interactions.
 func _handle_scrollbar_touch(event: InputEventScreenTouch, vertical: bool) -> void:
 	if event.pressed:
 		if vertical:
@@ -274,8 +263,7 @@ func _handle_scrollbar_touch(event: InputEventScreenTouch, vertical: bool) -> vo
 			h_scrollbar_dragging = false
 
 
-## Recursively removes focus from a node and all its children.
-## [param node] - The node to remove focus from
+## Recursively removes focus from the specified [param node] and all its children.
 func _remove_all_children_focus(node: Node) -> void:
 	if node is Control:
 		var control := node as Control

addons/SmoothScroll/helpers/scroll_layout.gd

@@ -6,9 +6,8 @@ extends RefCounted
 ## distances to boundaries, and handle margin/layout management.
 
 
-## Calculates container size on X axis without vertical scrollbar's width.
-## [param container] - The scroll container
-## [param content_margins] - StyleBox margins (left, top, right, bottom)
+## Calculates the available container size on the X axis without the vertical scrollbar's width. [br]
+## Uses [param container] dimensions and [param content_margins] for calculation.
 static func get_spare_size_x(container: Control, content_margins: Vector4) -> float:
 	var v_scroll_bar: ScrollBar = container.get_v_scroll_bar()
 	var size_x: float = container.size.x
@@ -20,9 +19,8 @@ static func get_spare_size_x(container: Control, content_margins: Vector4) -> fl
 	return max(size_x, 0.0)
 
 
-## Calculates container size on Y axis without horizontal scrollbar's height.
-## [param container] - The scroll container
-## [param content_margins] - StyleBox margins (left, top, right, bottom)
+## Calculates the available container size on the Y axis without the horizontal scrollbar's height. [br]
+## Uses [param container] dimensions and [param content_margins] for calculation.
 static func get_spare_size_y(container: Control, content_margins: Vector4) -> float:
 	var h_scroll_bar: ScrollBar = container.get_h_scroll_bar()
 	var size_y: float = container.size.y
@@ -34,20 +32,17 @@ static func get_spare_size_y(container: Control, content_margins: Vector4) -> fl
 	return max(size_y, 0.0)
 
 
-## Calculates container size without scrollbar sizes.
-## [param container] - The scroll container
-## [param content_margins] - StyleBox margins (left, top, right, bottom)
+## Calculates the available container size on both axes without scrollbar sizes. [br]
+## Uses [param container] dimensions and [param content_margins] for calculation.
 static func get_spare_size(container: Control, content_margins: Vector4) -> Vector2:
 	return Vector2(
 		get_spare_size_x(container, content_margins),
 		get_spare_size_y(container, content_margins)
 	)
 
 
-## Calculates the size difference between container and child node on X axis.
-## [param child] - The child control to measure
-## [param spare_size_x] - Available container width
-## [param clamp] - Whether to clamp child size to minimum of container size
+## Calculates the size difference between container and [param child] node on the X axis. [br]
+## When [param clamp] is [code]true[/code], clamps child size to minimum of [param spare_size_x].
 static func get_child_size_x_diff(child: Control, spare_size_x: float, clamp: bool) -> float:
 	var child_size_x: float = child.size.x * child.scale.x
 
@@ -57,10 +52,8 @@ static func get_child_size_x_diff(child: Control, spare_size_x: float, clamp: bo
 	return child_size_x - spare_size_x
 
 
-## Calculates the size difference between container and child node on Y axis.
-## [param child] - The child control to measure
-## [param spare_size_y] - Available container height
-## [param clamp] - Whether to clamp child size to minimum of container size
+## Calculates the size difference between container and [param child] node on the Y axis. [br]
+## When [param clamp] is [code]true[/code], clamps child size to minimum of [param spare_size_y].
 static func get_child_size_y_diff(child: Control, spare_size_y: float, clamp: bool) -> float:
 	var child_size_y: float = child.size.y * child.scale.y
 
@@ -70,11 +63,8 @@ static func get_child_size_y_diff(child: Control, spare_size_y: float, clamp: bo
 	return child_size_y - spare_size_y
 
 
-## Calculates the size difference between container and child node on both axes.
-## [param child] - The child control to measure
-## [param spare_size] - Available container size
-## [param clamp_x] - Whether to clamp child X size to minimum of container size
-## [param clamp_y] - Whether to clamp child Y size to minimum of container size
+## Calculates the size difference between container and [param child] node on both axes. [br]
+## When [param clamp_x] or [param clamp_y] is [code]true[/code], clamps respective child size to minimum of [param spare_size].
 static func get_child_size_diff(
 	child: Control,
 	spare_size: Vector2,
@@ -87,35 +77,30 @@ static func get_child_size_diff(
 	)
 
 
-## Calculates distance to left boundary.
-## [param child_pos_x] - Current X position of child
+## Calculates distance from the current [param child_pos_x] to the left boundary.
 static func get_left_dist(child_pos_x: float) -> float:
 	return child_pos_x
 
 
-## Calculates distance to right boundary.
-## [param child_pos_x] - Current X position of child
-## [param child_size_diff_x] - Size difference between container and child on X axis
+## Calculates distance from the current [param child_pos_x] to the right boundary. [br]
+## Uses [param child_size_diff_x] for the size difference calculation.
 static func get_right_dist(child_pos_x: float, child_size_diff_x: float) -> float:
 	return child_pos_x + child_size_diff_x
 
 
-## Calculates distance to top boundary.
-## [param child_pos_y] - Current Y position of child
+## Calculates distance from the current [param child_pos_y] to the top boundary.
 static func get_top_dist(child_pos_y: float) -> float:
 	return child_pos_y
 
 
-## Calculates distance to bottom boundary.
-## [param child_pos_y] - Current Y position of child
-## [param child_size_diff_y] - Size difference between container and child on Y axis
+## Calculates distance from the current [param child_pos_y] to the bottom boundary. [br]
+## Uses [param child_size_diff_y] for the size difference calculation.
 static func get_bottom_dist(child_pos_y: float, child_size_diff_y: float) -> float:
 	return child_pos_y + child_size_diff_y
 
 
-## Calculates distance to all four boundaries (left, right, top, bottom).
-## [param child_pos] - Current position of child
-## [param child_size_diff] - Size difference between container and child
+## Calculates distances from the current [param child_pos] to all four boundaries. [br]
+## Returns [Vector4] with distances: [code](left, right, top, bottom)[/code]. Uses [param child_size_diff] for calculations.
 static func get_boundary_dist(child_pos: Vector2, child_size_diff: Vector2) -> Vector4:
 	return Vector4(
 		get_left_dist(child_pos.x),
@@ -125,35 +110,30 @@ static func get_boundary_dist(child_pos: Vector2, child_size_diff: Vector2) -> V
 	)
 
 
-## Checks if content is currently beyond the top boundary.
-## [param pos_y] - Y position to check
+## Checks whether content at [param pos_y] is currently beyond the top boundary.
 static func is_outside_top_boundary(pos_y: float) -> bool:
 	return pos_y > 0.0
 
 
-## Checks if content is currently beyond the bottom boundary.
-## [param pos_y] - Y position to check
-## [param size_diff_y] - Size difference on Y axis
+## Checks whether content at [param pos_y] is currently beyond the bottom boundary. [br]
+## Uses [param size_diff_y] to determine the boundary position.
 static func is_outside_bottom_boundary(pos_y: float, size_diff_y: float) -> bool:
 	return pos_y < -size_diff_y
 
 
-## Checks if content is currently beyond the left boundary.
-## [param pos_x] - X position to check
+## Checks whether content at [param pos_x] is currently beyond the left boundary.
 static func is_outside_left_boundary(pos_x: float) -> bool:
 	return pos_x > 0.0
 
 
-## Checks if content is currently beyond the right boundary.
-## [param pos_x] - X position to check
-## [param size_diff_x] - Size difference on X axis
+## Checks whether content at [param pos_x] is currently beyond the right boundary. [br]
+## Uses [param size_diff_x] to determine the boundary position.
 static func is_outside_right_boundary(pos_x: float, size_diff_x: float) -> bool:
 	return pos_x < -size_diff_x
 
 
-## Updates and retrieves content margins from container's StyleBox.
-## [param container] - The scroll container
-## Returns Vector4 with margins (left, top, right, bottom)
+## Retrieves content margins from the [param container]'s StyleBox. [br]
+## Returns [Vector4] with margins in order: [code](left, top, right, bottom)[/code].
 static func get_content_margins(container: Control) -> Vector4:
 	var style_box: StyleBox = container.get_theme_stylebox("panel")
 	if style_box:
@@ -167,19 +147,15 @@ static func get_content_margins(container: Control) -> Vector4:
 		return Vector4.ZERO
 
 
-## Calculates the baseline offset for content positioning.
+## Calculates the baseline offset for content positioning from [param content_node] and [param current_scroll_pos]. [br]
 ## This captures the layout offset applied by StyleBox and content positioning.
-## [param content_node] - The content control node
-## [param current_scroll_pos] - Current scroll position
-## Returns the baseline offset as Vector2
 static func calculate_base_offset(content_node: Control, current_scroll_pos: Vector2) -> Vector2:
 	if not content_node:
 		return Vector2.ZERO
 	return content_node.position - current_scroll_pos
 
 
-## Calculates the initial base offset from margins.
-## [param content_margins] - StyleBox margins (left, top, right, bottom)
-## Returns the baseline offset as Vector2
+## Calculates the initial base offset from [param content_margins]. [br]
+## Returns the baseline offset as [Vector2].
 static func calculate_initial_offset(content_margins: Vector4) -> Vector2:
 	return Vector2(content_margins.x, content_margins.y)