Merge pull request #96923 from Repiteo/style/warning-admonition

Style: Add `WARNING:` as new comment admonition

13 files changed, 46 insertions, 34 deletions

diff --git a/core/input/input_builders.py b/core/input/input_builders.py
index ae848f4e7c..3685e726b4 100644
--- a/core/input/input_builders.py
+++ b/core/input/input_builders.py
@@ -33,7 +33,7 @@ def make_default_controller_mappings(target, source, env):
                     guid = line_parts[0]
                     if guid in platform_mappings[current_platform]:
                         g.write(
-                            "// WARNING - DATABASE {} OVERWROTE PRIOR MAPPING: {} {}\n".format(
+                            "// WARNING: DATABASE {} OVERWROTE PRIOR MAPPING: {} {}\n".format(
                                 src_path, current_platform, platform_mappings[current_platform][guid]
                             )
                         )
diff --git a/core/io/packet_peer.cpp b/core/io/packet_peer.cpp
index 0329ace313..614f81c42a 100644
--- a/core/io/packet_peer.cpp
+++ b/core/io/packet_peer.cpp
@@ -299,7 +299,7 @@ Ref<StreamPeer> PacketPeerStream::get_stream_peer() const {
 
 void PacketPeerStream::set_input_buffer_max_size(int p_max_size) {
 	ERR_FAIL_COND_MSG(p_max_size < 0, "Max size of input buffer size cannot be smaller than 0.");
-	//warning may lose packets
+	// WARNING: May lose packets.
 	ERR_FAIL_COND_MSG(ring_buffer.data_left(), "Buffer in use, resizing would cause loss of data.");
 	ring_buffer.resize(nearest_shift(next_power_of_2(p_max_size + 4)) - 1);
 	input_buffer.resize(next_power_of_2(p_max_size + 4));
diff --git a/core/math/transform_2d.h b/core/math/transform_2d.h
index 476577508f..1ee7d3d84f 100644
--- a/core/math/transform_2d.h
+++ b/core/math/transform_2d.h
@@ -39,16 +39,19 @@
 class String;
 
 struct [[nodiscard]] Transform2D {
-	// Warning #1: basis of Transform2D is stored differently from Basis. In terms of columns array, the basis matrix looks like "on paper":
+	// WARNING: The basis of Transform2D is stored differently from Basis.
+	// In terms of columns array, the basis matrix looks like "on paper":
 	// M = (columns[0][0] columns[1][0])
 	//     (columns[0][1] columns[1][1])
-	// This is such that the columns, which can be interpreted as basis vectors of the coordinate system "painted" on the object, can be accessed as columns[i].
-	// Note that this is the opposite of the indices in mathematical texts, meaning: $M_{12}$ in a math book corresponds to columns[1][0] here.
+	// This is such that the columns, which can be interpreted as basis vectors
+	// of the coordinate system "painted" on the object, can be accessed as columns[i].
+	// NOTE: This is the opposite of the indices in mathematical texts,
+	// meaning: $M_{12}$ in a math book corresponds to columns[1][0] here.
 	// This requires additional care when working with explicit indices.
 	// See https://en.wikipedia.org/wiki/Row-_and_column-major_order for further reading.
 
-	// Warning #2: 2D be aware that unlike 3D code, 2D code uses a left-handed coordinate system: Y-axis points down,
-	// and angle is measure from +X to +Y in a clockwise-fashion.
+	// WARNING: Be aware that unlike 3D code, 2D code uses a left-handed coordinate system:
+	// Y-axis points down, and angle is measure from +X to +Y in a clockwise-fashion.
 
 	Vector2 columns[3];
 
diff --git a/editor/plugins/tiles/tile_set_atlas_source_editor.h b/editor/plugins/tiles/tile_set_atlas_source_editor.h
index 957f768429..c1a8338f81 100644
--- a/editor/plugins/tiles/tile_set_atlas_source_editor.h
+++ b/editor/plugins/tiles/tile_set_atlas_source_editor.h
@@ -177,7 +177,7 @@ private:
 
 		DRAG_TYPE_MAY_POPUP_MENU,
 
-		// Warning: keep in this order.
+		// WARNING: Keep in this order.
 		DRAG_TYPE_RESIZE_TOP_LEFT,
 		DRAG_TYPE_RESIZE_TOP,
 		DRAG_TYPE_RESIZE_TOP_RIGHT,
diff --git a/modules/gdscript/gdscript_compiler.cpp b/modules/gdscript/gdscript_compiler.cpp
index eebf282633..f4f445e096 100644
--- a/modules/gdscript/gdscript_compiler.cpp
+++ b/modules/gdscript/gdscript_compiler.cpp
@@ -2629,9 +2629,10 @@ Error GDScriptCompiler::_parse_setter_getter(GDScript *p_script, const GDScriptP
 	return err;
 }
 
-// Prepares given script, and inner class scripts, for compilation. It populates class members and initializes method
-// RPC info for its base classes first, then for itself, then for inner classes.
-// Warning: this function cannot initiate compilation of other classes, or it will result in cyclic dependency issues.
+// Prepares given script, and inner class scripts, for compilation. It populates class members and
+// initializes method RPC info for its base classes first, then for itself, then for inner classes.
+// WARNING: This function cannot initiate compilation of other classes, or it will result in
+// cyclic dependency issues.
 Error GDScriptCompiler::_prepare_compilation(GDScript *p_script, const GDScriptParser::ClassNode *p_class, bool p_keep_state) {
 	if (parsed_classes.has(p_script)) {
 		return OK;
diff --git a/modules/godot_physics_2d/godot_body_pair_2d.cpp b/modules/godot_physics_2d/godot_body_pair_2d.cpp
index 6c2d28dc92..98f11d6c07 100644
--- a/modules/godot_physics_2d/godot_body_pair_2d.cpp
+++ b/modules/godot_physics_2d/godot_body_pair_2d.cpp
@@ -161,11 +161,13 @@ void GodotBodyPair2D::_validate_contacts() {
 	}
 }
 
-// _test_ccd prevents tunneling by slowing down a high velocity body that is about to collide so that next frame it will be at an appropriate location to collide (i.e. slight overlap)
-// Warning: the way velocity is adjusted down to cause a collision means the momentum will be weaker than it should for a bounce!
-// Process: only proceed if body A's motion is high relative to its size.
-// cast forward along motion vector to see if A is going to enter/pass B's collider next frame, only proceed if it does.
-// adjust the velocity of A down so that it will just slightly intersect the collider instead of blowing right past it.
+// `_test_ccd` prevents tunneling by slowing down a high velocity body that is about to collide so
+// that next frame it will be at an appropriate location to collide (i.e. slight overlap).
+// WARNING: The way velocity is adjusted down to cause a collision means the momentum will be
+// weaker than it should for a bounce!
+// Process: Only proceed if body A's motion is high relative to its size.
+// Cast forward along motion vector to see if A is going to enter/pass B's collider next frame, only proceed if it does.
+// Adjust the velocity of A down so that it will just slightly intersect the collider instead of blowing right past it.
 bool GodotBodyPair2D::_test_ccd(real_t p_step, GodotBody2D *p_A, int p_shape_A, const Transform2D &p_xform_A, GodotBody2D *p_B, int p_shape_B, const Transform2D &p_xform_B) {
 	Vector2 motion = p_A->get_linear_velocity() * p_step;
 	real_t mlen = motion.length();
diff --git a/modules/godot_physics_2d/godot_step_2d.cpp b/modules/godot_physics_2d/godot_step_2d.cpp
index bbaec8be2b..418b9313e8 100644
--- a/modules/godot_physics_2d/godot_step_2d.cpp
+++ b/modules/godot_physics_2d/godot_step_2d.cpp
@@ -251,14 +251,14 @@ void GodotStep2D::step(GodotSpace2D *p_space, real_t p_delta) {
 
 	/* PRE-SOLVE CONSTRAINT ISLANDS */
 
-	// Warning: This doesn't run on threads, because it involves thread-unsafe processing.
+	// WARNING: This doesn't run on threads, because it involves thread-unsafe processing.
 	for (uint32_t island_index = 0; island_index < island_count; ++island_index) {
 		_pre_solve_island(constraint_islands[island_index]);
 	}
 
 	/* SOLVE CONSTRAINT ISLANDS */
 
-	// Warning: _solve_island modifies the constraint islands for optimization purpose,
+	// WARNING: `_solve_island` modifies the constraint islands for optimization purpose,
 	// their content is not reliable after these calls and shouldn't be used anymore.
 	group_task = WorkerThreadPool::get_singleton()->add_template_group_task(this, &GodotStep2D::_solve_island, nullptr, island_count, -1, true, SNAME("Physics2DConstraintSolveIslands"));
 	WorkerThreadPool::get_singleton()->wait_for_group_task_completion(group_task);
diff --git a/modules/godot_physics_3d/godot_body_pair_3d.cpp b/modules/godot_physics_3d/godot_body_pair_3d.cpp
index 84fae73616..d689271ac7 100644
--- a/modules/godot_physics_3d/godot_body_pair_3d.cpp
+++ b/modules/godot_physics_3d/godot_body_pair_3d.cpp
@@ -161,11 +161,13 @@ void GodotBodyPair3D::validate_contacts() {
 	}
 }
 
-// _test_ccd prevents tunneling by slowing down a high velocity body that is about to collide so that next frame it will be at an appropriate location to collide (i.e. slight overlap)
-// Warning: the way velocity is adjusted down to cause a collision means the momentum will be weaker than it should for a bounce!
-// Process: only proceed if body A's motion is high relative to its size.
-// cast forward along motion vector to see if A is going to enter/pass B's collider next frame, only proceed if it does.
-// adjust the velocity of A down so that it will just slightly intersect the collider instead of blowing right past it.
+// `_test_ccd` prevents tunneling by slowing down a high velocity body that is about to collide so
+// that next frame it will be at an appropriate location to collide (i.e. slight overlap).
+// WARNING: The way velocity is adjusted down to cause a collision means the momentum will be
+// weaker than it should for a bounce!
+// Process: Only proceed if body A's motion is high relative to its size.
+// Cast forward along motion vector to see if A is going to enter/pass B's collider next frame, only proceed if it does.
+// Adjust the velocity of A down so that it will just slightly intersect the collider instead of blowing right past it.
 bool GodotBodyPair3D::_test_ccd(real_t p_step, GodotBody3D *p_A, int p_shape_A, const Transform3D &p_xform_A, GodotBody3D *p_B, int p_shape_B, const Transform3D &p_xform_B) {
 	GodotShape3D *shape_A_ptr = p_A->get_shape(p_shape_A);
 
diff --git a/modules/godot_physics_3d/godot_step_3d.cpp b/modules/godot_physics_3d/godot_step_3d.cpp
index d09a3b4e6d..b6cec4ba59 100644
--- a/modules/godot_physics_3d/godot_step_3d.cpp
+++ b/modules/godot_physics_3d/godot_step_3d.cpp
@@ -355,14 +355,14 @@ void GodotStep3D::step(GodotSpace3D *p_space, real_t p_delta) {
 
 	/* PRE-SOLVE CONSTRAINT ISLANDS */
 
-	// Warning: This doesn't run on threads, because it involves thread-unsafe processing.
+	// WARNING: This doesn't run on threads, because it involves thread-unsafe processing.
 	for (uint32_t island_index = 0; island_index < island_count; ++island_index) {
 		_pre_solve_island(constraint_islands[island_index]);
 	}
 
 	/* SOLVE CONSTRAINT ISLANDS */
 
-	// Warning: _solve_island modifies the constraint islands for optimization purpose,
+	// WARNING: `_solve_island` modifies the constraint islands for optimization purpose,
 	// their content is not reliable after these calls and shouldn't be used anymore.
 	group_task = WorkerThreadPool::get_singleton()->add_template_group_task(this, &GodotStep3D::_solve_island, nullptr, island_count, -1, true, SNAME("Physics3DConstraintSolveIslands"));
 	WorkerThreadPool::get_singleton()->wait_for_group_task_completion(group_task);
diff --git a/platform/windows/display_server_windows.cpp b/platform/windows/display_server_windows.cpp
index ed9d5244a3..5b166d0075 100644
--- a/platform/windows/display_server_windows.cpp
+++ b/platform/windows/display_server_windows.cpp
@@ -3962,9 +3962,9 @@ LRESULT DisplayServerWindows::WndProc(HWND hWnd, UINT uMsg, WPARAM wParam, LPARA
 		}
 	}
 
-	// WARNING: we get called with events before the window is registered in our collection
+	// WARNING: We get called with events before the window is registered in our collection
 	// specifically, even the call to CreateWindowEx already calls here while still on the stack,
-	// so there is no way to store the window handle in our collection before we get here
+	// so there is no way to store the window handle in our collection before we get here.
 	if (!window_created) {
 		// don't let code below operate on incompletely initialized window objects or missing window_id
 		return _handle_early_window_message(hWnd, uMsg, wParam, lParam);
diff --git a/platform/windows/gl_manager_windows_native.cpp b/platform/windows/gl_manager_windows_native.cpp
index 8590c46d12..af703f4dfa 100644
--- a/platform/windows/gl_manager_windows_native.cpp
+++ b/platform/windows/gl_manager_windows_native.cpp
@@ -452,8 +452,8 @@ Error GLManagerNative_Windows::window_create(DisplayServer::WindowID p_window_id
 		return FAILED;
 	}
 
-	// WARNING: p_window_id is an eternally growing integer since popup windows keep coming and going
-	// and each of them has a higher id than the previous, so it must be used in a map not a vector
+	// WARNING: `p_window_id` is an eternally growing integer since popup windows keep coming and going
+	// and each of them has a higher id than the previous, so it must be used in a map not a vector.
 	_windows[p_window_id] = win;
 
 	// make current
diff --git a/servers/rendering/renderer_rd/shaders/effects/ssao.glsl b/servers/rendering/renderer_rd/shaders/effects/ssao.glsl
index 8c50bb544d..41a262b2e8 100644
--- a/servers/rendering/renderer_rd/shaders/effects/ssao.glsl
+++ b/servers/rendering/renderer_rd/shaders/effects/ssao.glsl
@@ -50,11 +50,14 @@ const int num_taps[5] = { 3, 5, 12, 0, 0 };
 //
 #define SSAO_DETAIL_AO_ENABLE_AT_QUALITY_PRESET (1) // whether to use detail; to disable simply set to 99 or similar
 //
-#define SSAO_DEPTH_MIPS_ENABLE_AT_QUALITY_PRESET (2) // !!warning!! the MIP generation on the C++ side will be enabled on quality preset 2 regardless of this value, so if changing here, change the C++ side too
+// WARNING: The MIP generation on the C++ side will be enabled on quality preset 2 regardless of
+// this value, so if changing here, change the C++ side too.
+#define SSAO_DEPTH_MIPS_ENABLE_AT_QUALITY_PRESET (2)
 #define SSAO_DEPTH_MIPS_GLOBAL_OFFSET (-4.3) // best noise/quality/performance tradeoff, found empirically
 //
-// !!warning!! the edge handling is hard-coded to 'disabled' on quality level 0, and enabled above, on the C++ side; while toggling it here will work for
-// testing purposes, it will not yield performance gains (or correct results)
+// WARNING: The edge handling is hard-coded to 'disabled' on quality level 0, and enabled above,
+// on the C++ side; while toggling it here will work for testing purposes, it will not yield
+// performance gains (or correct results).
 #define SSAO_DEPTH_BASED_EDGES_ENABLE_AT_QUALITY_PRESET (1)
 //
 #define SSAO_REDUCE_RADIUS_NEAR_SCREEN_BORDER_ENABLE_AT_QUALITY_PRESET (1)
diff --git a/servers/rendering/renderer_rd/shaders/effects/ssil.glsl b/servers/rendering/renderer_rd/shaders/effects/ssil.glsl
index 0b623c1d4e..6dbd6c82cb 100644
--- a/servers/rendering/renderer_rd/shaders/effects/ssil.glsl
+++ b/servers/rendering/renderer_rd/shaders/effects/ssil.glsl
@@ -49,8 +49,9 @@ const int num_taps[5] = { 3, 5, 12, 0, 0 };
 #define SSIL_DEPTH_MIPS_ENABLE_AT_QUALITY_PRESET (2)
 #define SSIL_DEPTH_MIPS_GLOBAL_OFFSET (-4.3) // best noise/quality/performance tradeoff, found empirically
 //
-// !!warning!! the edge handling is hard-coded to 'disabled' on quality level 0, and enabled above, on the C++ side; while toggling it here will work for
-// testing purposes, it will not yield performance gains (or correct results)
+// WARNING: The edge handling is hard-coded to 'disabled' on quality level 0, and enabled above,
+// on the C++ side; while toggling it here will work for testing purposes, it will not yield
+// performance gains (or correct results).
 #define SSIL_DEPTH_BASED_EDGES_ENABLE_AT_QUALITY_PRESET (1)
 //
 #define SSIL_REDUCE_RADIUS_NEAR_SCREEN_BORDER_ENABLE_AT_QUALITY_PRESET (1)