Fix miscellaneous oddities around the class reference (part 6) #107536

Mickeon · 2025-06-14T15:14:28Z

Continuation of #107143

This PR addressed yet yet another huge chunk of class reference oddities I remembered to note down for later while localizing the class reference. Some of these are clear typos, some are inconsistencies, some are just awkward.

Of particular note:

Standardize the description for language everywhere
- "Language code used for line-breaking and text shaping algorithms [...]" and similar
Replace a very nasty "The color's alpha channel" pun
Reword EditorSetting's network/connection/network_mode to be somewhat less awkward
Reword the following for clarity:
- Window's move_to_center
- Sprite2D's is_pixel_opaque
- StreamPeer's get_data and get_double
- TabBar's tab_close_pressed
- PortableCompressedTexture2D's keep_compressed_buffer
Shifted VoxelGI's size description around
Mention CanvasItem in the deprecated warnings of the oversampling properties
Remove redundant "deprecated" from some descriptions
- There is no point stating this in the description itself. The deprecation warning is already enough
Reword GeometryInstance3D's cast_shadow to be more meaningful
Remove "0 = off [...]" from ProjectSetting's xr/openxr/foveation_level
- We genuinely don't do this anywhere, and it's not particularly polished
Removed "user signals" from Script's get_script_signal_list
- This is hugely misleading, because "user signals" are separate and created through add_user_signal
Add [code] tags to TextServer's string_to_upper & similar
- For consistency with the corresponding String methods
Add link to RFC 645 specifications to a few of WebSocketPeer's descriptions
Replace a few occurrences of "timely" and "forward renderer" with more common alternatives
Fix missing word in all array's get methods
Fix typo in Control's leading description
- This has been so long-standing, I am not sure if I should actually fix it, because it will invalidate localizations really badly
Fix DisplayServer's screen_get_pixel claiming it returns a whole screenshot and literally the entire [Color] type
Fix missed standardization of horizontal_alignment properties, leading to duplicate translation strings
Fix "parameters" being referred as "arguments" in a few places
Fix some missing articles on the way

For some of the descriptions affected, additional tweaks have been made to justify a whole translation string change.

Mickeon · 2025-06-14T15:21:03Z

doc/classes/GeometryInstance3D.xml

 	<members>
 		<member name="cast_shadow" type="int" setter="set_cast_shadows_setting" getter="get_cast_shadows_setting" enum="GeometryInstance3D.ShadowCastingSetting" default="1">
-			The selected shadow casting flag.
+			The mode used to cast shadows from this instance.


Alternative which I am genuinely not sure.

Suggested change

The mode used to cast shadows from this instance.

The way in which this instance casts shadows.

Mickeon · 2025-06-14T15:21:34Z

doc/classes/FileAccess.xml

 			<param index="0" name="file" type="String" />
 			<description>
-				Returns file size in bytes, or [code]-1[/code] on error.
+				Returns the size of the file at the given path, in bytes, or [code]-1[/code] on error.


Yes, file is actually a file path. Put a pin on this.

Maybe it should be changed to path, renaming argument is not breaking change.

Mickeon · 2025-06-14T15:22:46Z

doc/classes/RenderingServer.xml

 			<description>
 				Creates a texture based on a native handle that was created outside of Godot's renderer.
-				[b]Note:[/b] If using only the rendering device renderer, it's recommend to use [method RenderingDevice.texture_create_from_extension] together with [method RenderingServer.texture_rd_create], rather than this method. It will give you much more control over the texture's format and usage.
+				[b]Note:[/b] If using only the rendering device renderer, it's recommend to use [method RenderingDevice.texture_create_from_extension] together with [method RenderingServer.texture_rd_create], rather than this method. This way, the texture's format and usage can be controlled more effectively.


The reason this was done is because the previous sentence is indirect (no "you"). But, alternatively:

Suggested change

[b]Note:[/b] If using only the rendering device renderer, it's recommend to use [method RenderingDevice.texture_create_from_extension] together with [method RenderingServer.texture_rd_create], rather than this method. This way, the texture's format and usage can be controlled more effectively.

[b]Note:[/b] If using only the rendering device renderer, it's recommend to use [method RenderingDevice.texture_create_from_extension] together with [method RenderingServer.texture_rd_create], rather than this method. You will be able to control the texture's format and usage more effectively.

Mickeon · 2025-06-14T15:23:19Z

doc/classes/ProjectSettings.xml

 		</member>
 		<member name="threading/worker_pool/max_threads" type="int" setter="" getter="" default="-1">
-			Maximum number of threads to be used by [WorkerThreadPool]. Value of [code]-1[/code] means [code]1[/code] on Web, or a number of [i]logical[/i] CPU cores available on other platforms (see [method OS.get_processor_count]).
+			Maximum number of threads to be used by [WorkerThreadPool]. On Web, a value of [code]-1[/code] means [code]1[/code]. On other platforms, it means all [i]logical[/i] CPU cores available (see [method OS.get_processor_count]).


Something about this still bothers me.

Mickeon · 2025-06-14T15:24:00Z

doc/classes/ProjectSettings.xml

 		</member>
 		<member name="rendering/textures/vram_compression/cache_gpu_compressor" type="bool" setter="" getter="" default="true">
-			If [code]true[/code], the GPU texture compressor will cache the local RenderingDevice and its resources (shaders and pipelines), allowing for faster subsequent imports at a memory cost.
+			If [code]true[/code], the GPU texture compressor will cache the local RenderingDevice and its resources (shaders and pipelines), making subsequent imports faster at the cost of increased memory usage.


Maybe this was fine before? It was very succinct, maybe too much.

Mickeon · 2025-06-14T15:24:54Z

doc/classes/Object.xml

 				[b]Note:[/b] If the [param callable]'s object is freed, the connection will be lost.
 				[b]Note:[/b] In GDScript, it is generally recommended to connect signals with [method Signal.connect] instead.
-				[b]Note:[/b] This operation (and all other signal related operations) is thread-safe.
+				[b]Note:[/b] This method, and all other signal-related methods, are thread-safe.


I genuinely don't think this note needs to exist, especially specifically only in Object.connect, but I digress.

doc/classes/FoldableContainer.xml

bruvzg

GUI/TextServer related changes look good.

doc/classes/EditorExportPlatform.xml

bruvzg · 2025-06-15T20:17:19Z

doc/classes/FileAccess.xml

 			<param index="0" name="file" type="String" />
 			<description>
-				Returns file size in bytes, or [code]-1[/code] on error.
+				Returns the size of the file at the given path, in bytes, or [code]-1[/code] on error.


Maybe it should be changed to path, renaming argument is not breaking change.

doc/classes/TextServer.xml

doc/classes/VoxelGI.xml

doc/classes/TextServerExtension.xml

doc/classes/TextServer.xml

Repiteo · 2025-11-18T20:10:51Z

Needs rebase

Mickeon · 2025-11-25T20:23:49Z

Rebased.
I must note that by the time this PR was made two things were changed:

SVGTexture had been renamed to DPITexture, but there are just a few awkward references to its old name.
font_set_oversampling & co. became no longer deprecated, so a few changes to this PR have been voided.

I decided to not touch these here because the stalling for documentation PRs is maddening.

Repiteo

That's entirely fair. Given this is already a part 6, we won't have to worry about a lack of follow-ups

akien-mga · 2025-11-26T22:50:08Z

Thanks!

Mickeon · 2025-11-26T22:50:28Z

😌

Mickeon added this to the 4.5 milestone Jun 14, 2025

Mickeon requested review from a team as code owners June 14, 2025 15:14

Mickeon added bug enhancement documentation labels Jun 14, 2025

Mickeon removed the request for review from a team June 14, 2025 15:15

Mickeon force-pushed the documentation-miscellaneous-oddities-part-6 branch from 765a896 to 5735913 Compare June 14, 2025 15:16

Mickeon commented Jun 14, 2025

View reviewed changes

Mickeon modified the milestones: 4.5, 4.x Jun 14, 2025

Mickeon force-pushed the documentation-miscellaneous-oddities-part-6 branch 2 times, most recently from c82c970 to 216435e Compare June 15, 2025 19:47

Mickeon requested a review from bruvzg June 15, 2025 19:47

bruvzg reviewed Jun 15, 2025

View reviewed changes

AThousandShips reviewed Jun 16, 2025

View reviewed changes

doc/classes/VoxelGI.xml Outdated Show resolved Hide resolved

doc/classes/TextServerExtension.xml Outdated Show resolved Hide resolved

doc/classes/TextServer.xml Outdated Show resolved Hide resolved

Mickeon force-pushed the documentation-miscellaneous-oddities-part-6 branch from 216435e to 6df0ff0 Compare June 16, 2025 15:48

Mickeon requested review from AThousandShips and bruvzg June 16, 2025 15:50

Mickeon modified the milestones: 4.x, 4.5 Jun 16, 2025

This was referenced Jun 16, 2025

Reword text_editor/completion/add_type_hints's description #107601

Merged

Restore per font oversampling override. #107708

Merged

Repiteo added the cherrypick:4.5 Considered for cherry-picking into a future 4.5.x release label Sep 5, 2025

Repiteo modified the milestones: 4.5, 4.6 Sep 5, 2025

Fix miscellaneous oddities around the class reference (part 6)

be0c688

Mickeon force-pushed the documentation-miscellaneous-oddities-part-6 branch from 6df0ff0 to be0c688 Compare November 25, 2025 20:21

Repiteo approved these changes Nov 26, 2025

View reviewed changes

akien-mga merged commit d57a598 into godotengine:master Nov 26, 2025
20 checks passed

Mickeon deleted the documentation-miscellaneous-oddities-part-6 branch November 26, 2025 22:50

This was referenced Nov 26, 2025

Rename file parameter to path in many FileAccess methods #113217

Open

Fix miscellaneous oddities around the class reference (part 7) #113261

Merged

	The mode used to cast shadows from this instance.
	The way in which this instance casts shadows.

	[b]Note:[/b] If using only the rendering device renderer, it's recommend to use [method RenderingDevice.texture_create_from_extension] together with [method RenderingServer.texture_rd_create], rather than this method. This way, the texture's format and usage can be controlled more effectively.
	[b]Note:[/b] If using only the rendering device renderer, it's recommend to use [method RenderingDevice.texture_create_from_extension] together with [method RenderingServer.texture_rd_create], rather than this method. You will be able to control the texture's format and usage more effectively.

Uh oh!

Fix miscellaneous oddities around the class reference (part 6) #107536

Fix miscellaneous oddities around the class reference (part 6) #107536

Conversation

Mickeon commented Jun 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bruvzg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Repiteo commented Nov 18, 2025

Uh oh!

Mickeon commented Nov 25, 2025

Uh oh!

Repiteo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

akien-mga commented Nov 26, 2025

Uh oh!

Mickeon commented Nov 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Mickeon commented Jun 14, 2025 •

edited

Loading