Docs: Proofreading for grammar and spelling #112123
Conversation
|
This is going to be a really nasty PR for all localizations so I would be wary and look for other things that could be tweaked in each description "while you are at it" |
|
I've gone around for various cases, but can go through these for additional cleanups |
AThousandShips
force-pushed
the
fix_doc_spelling
branch
from
9a37096 to
b64be2d
Compare
|
I'm reviewing this really steadily. Be scared of an incoming flood of "while you're at it". |
| Sets if the agent uses the 2D avoidance or the 3D avoidance while avoidance is enabled. | ||
| If [code]true[/code] the agent calculates avoidance velocities in 3D for the xyz-axis, e.g. for games that take place in air, underwater or space. The 3D using agent only avoids other 3D avoidance using agent's. The 3D using agent only reacts to radius based avoidance obstacles. The 3D using agent ignores any vertices based obstacles. The 3D using agent only avoids other 3D using agent's. | ||
| If [code]false[/code] the agent calculates avoidance velocities in 2D along the xz-axis ignoring the y-axis. The 2D using agent only avoids other 2D avoidance using agent's. The 2D using agent reacts to radius avoidance obstacles. The 2D using agent reacts to vertices based avoidance obstacles. The 2D using agent only avoids other 2D using agent's. 2D using agents will ignore other 2D using agents or obstacles that are below their current position or above their current position including the agents height in 2D avoidance. | ||
| If [code]true[/code] the agent calculates avoidance velocities in 3D for the xyz-axes, e.g. for games that take place in air, underwater, or space. The 3D agent only avoids other 3D avoidance agents. The 3D agent only reacts to radius based avoidance obstacles. The 3D agent ignores any vertices based obstacles. The 3D agent only avoids other 3D agents. |
There was a problem hiding this comment.
There's many cases of "2D/3D avoidance using agents" across the class reference I would address on their own. It's a very weird way to put it, and I assume it's done to avoid ambiguity with NavigationAgent2D. If that were to be kept, it should be "2D/3D-using", "2D/3D-avoidance-using", or similar, hyphenated.
(But I'd rather not because it's so, so nasty to localize but English can work like this).
|
Thank you I'll go over these! |
| <member name="bone_size" type="int" setter="set_bone_size" getter="get_bone_size" default="0"> | ||
| The amount of bones in retargeting section's [BoneMap] editor. For example, [SkeletonProfileHumanoid] has 56 bones. | ||
| The size of elements in [BoneMap] updates when changing this property in it's assigned [SkeletonProfile]. | ||
| The size of elements in [BoneMap] updates when changing this property in its assigned [SkeletonProfile]. |
There was a problem hiding this comment.
This entire description has a bit of botched English, I'm not quite sure what it means.
| <description> | ||
| Resets a simulating state with respect to the current bone pose. | ||
| It is useful to prevent the simulation result getting violent. For example, calling this immediately after a call to [method AnimationPlayer.play] without a fading, or within the previous [signal SkeletonModifier3D.modification_processed] signal if it's condition changes significantly. | ||
| It is useful to prevent the simulation result getting violent. For example, calling this immediately after a call to [method AnimationPlayer.play] without a fading, or within the previous [signal SkeletonModifier3D.modification_processed] signal if its condition changes significantly. |
There was a problem hiding this comment.
Kinda same... It's a bit awkward, I don't quite understand. "with respect to"? "If its condition", but it isn't talking about programming conditions, it's probably referring to the state.
| [b]Note:[/b] The driver in use can be overridden at runtime via the [code]--audio-driver[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url]. | ||
| </member> | ||
| <member name="audio/driver/enable_input" type="bool" setter="" getter="" default="false"> | ||
| If [code]true[/code], microphone input will be allowed. This requires appropriate permissions to be set when exporting to Android or iOS. |
There was a problem hiding this comment.
I'd personally move "This requires appropriate permissions [...]" to a note below and actually list the respective settings. But that's probably for another time. The EditorExportPlatform settings can be referenced directly but aren't quite designed to be seen (that is to say they look ugly in the docs).
| <param index="0" name="max_output_size" type="int" /> | ||
| <param index="1" name="compression_mode" type="int" default="0" /> | ||
| <description> | ||
| Returns a new [PackedByteArray] with the data decompressed. Set the compression mode using one of [enum FileAccess.CompressionMode]'s constants. [b]This method only accepts brotli, gzip, and deflate compression modes.[/b] |
There was a problem hiding this comment.
That sentence in bold should be an "Important" admonition, but it's far from the only oddity like this. I'm noting this down for later.
AThousandShips
force-pushed
the
fix_doc_spelling
branch
from
b64be2d to
512ad87
Compare
|
Applied the suggestions and a few additional details, will go over again more thoroughly tomorrow or next week |
Minor cases with confusion over `it's`, `its`, and the possessive.
AThousandShips
force-pushed
the
fix_doc_spelling
branch
from
512ad87 to
54997e5
Compare
| </brief_description> | ||
| <description> | ||
| Generic 3D position hint for editing. It's just like a plain [Node3D], but it displays as a cross in the 3D editor at all times. | ||
| Generic 3D position hint for editing. This is like a plain [Node3D], but it displays as a cross in the 3D editor. While the node is selected, you can adjust the cross's visual size by using the gizmo in the 3D editor. |
There was a problem hiding this comment.
Hold on. That would be nice, but you actually cannot resize the 3D cross via the gizmos, only in Marker2D. Yeah, they're really that simple...
| Generic 3D position hint for editing. This is like a plain [Node3D], but it displays as a cross in the 3D editor. While the node is selected, you can adjust the cross's visual size by using the gizmo in the 3D editor. | |
| Generic 3D position hint for editing. This is like a plain [Node3D], but it displays as a cross in the 3D editor. |
There was a problem hiding this comment.
The marker scales though? I naturally tested it before I added this, or did your suggestion for 2D mean something else than scaling the marker node? (If that's not what you meant by the 2D description that needs to be clarified what it actually means)
There was a problem hiding this comment.
Okay, so, I guess I was confused by the original description which is still essentially the same currently, just reordered a bit.
It turns out that neither of the two markers have special gizmos to control their gizmo_extents property, yet the existing description strong implies they exist. Changing the scale via the "transform gizmo", which is what the description originally meant, is not just visual. As ignorant as I was for thinking something different, this is quite misleading.
There was a problem hiding this comment.
Then I'll drop both descriptions to avoid confusion
| </member> | ||
| <member name="target" type="Transform3D" setter="set_target_transform" getter="get_target_transform" default="Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)"> | ||
| First target of the IK chain where the tip bone is placed and, if [member override_tip_basis] is [code]true[/code], how the tip bone is rotated. If a [member target_node] path is available the nodes transform is used instead and this property is ignored. | ||
| First target of the IK chain where the tip bone is placed and, if [member override_tip_basis] is [code]true[/code], how the tip bone is rotated. If a [member target_node] path is available the node's transform is used instead and this property is ignored. |
There was a problem hiding this comment.
Ooh... this is a bit ambiguous because it could also be interpreted as "this node". Judging by the description of target_node, the following suggestion should be okay (albeit a bit inconsistent to the other descriptions in this class):
| First target of the IK chain where the tip bone is placed and, if [member override_tip_basis] is [code]true[/code], how the tip bone is rotated. If a [member target_node] path is available the node's transform is used instead and this property is ignored. | |
| First target of the IK chain where the tip bone is placed and, if [member override_tip_basis] is [code]true[/code], how the tip bone is rotated. If [member target_node] points to a valid node, that node's transform is used instead and this property is ignored. |
or
| First target of the IK chain where the tip bone is placed and, if [member override_tip_basis] is [code]true[/code], how the tip bone is rotated. If a [member target_node] path is available the node's transform is used instead and this property is ignored. | |
| First target of the IK chain where the tip bone is placed and, if [member override_tip_basis] is [code]true[/code], how the tip bone is rotated. If [member target_node] points to a valid node, its transform is used instead and this property is ignored. |
| </brief_description> | ||
| <description> | ||
| Visual shader graphs consist of various nodes. Each node in the graph is a separate object and they are represented as a rectangular boxes with title and a set of properties. Each node also has connection ports that allow to connect it to another nodes and control the flow of the shader. | ||
| Visual shader graphs consist of various nodes. Each node in the graph is a separate object and they are represented as a rectangular boxes with title and a set of properties. Each node also has connection ports that allow to connect it to other nodes and control the flow of the shader. |
There was a problem hiding this comment.
The first sentence says "graphs" (plural), but then it switches to "a graph" (singular)...
Plus a few other awkward sentences, to the point where it may be better to just rewrite this a bit.
Maybe..? :
| Visual shader graphs consist of various nodes. Each node in the graph is a separate object and they are represented as a rectangular boxes with title and a set of properties. Each node also has connection ports that allow to connect it to other nodes and control the flow of the shader. | |
| A visual shader graph consists of various nodes. Each node in a graph is an individual resource, represented as a rectangular box containing a title and several related properties. Each node can also be connected to other nodes through their connection ports in order to control the shader's flow. |
There was a problem hiding this comment.
Mixing singular and plural isn't a problem I'd say at all, though it should have been "each node in a graph" rather than "the graph" to make it less awkward, will look at this one
| [CameraAttributesPhysical] is used to set rendering settings based on a physically-based camera's settings. It is responsible for exposure, auto-exposure, and depth of field. | ||
| When used in a [WorldEnvironment] it provides default settings for exposure, auto-exposure, and depth of field that will be used by all cameras without their own [CameraAttributes], including the editor camera. When used in a [Camera3D] it will override any [CameraAttributes] set in the [WorldEnvironment] and will override the [Camera3D]s [member Camera3D.far], [member Camera3D.near], [member Camera3D.fov], and [member Camera3D.keep_aspect] properties. When used in [VoxelGI] or [LightmapGI], only the exposure settings will be used. | ||
| When used in a [WorldEnvironment] it provides default settings for exposure, auto-exposure, and depth of field that will be used by all cameras without their own [CameraAttributes], including the editor camera. When used in a [Camera3D] it will override any [CameraAttributes] set in the [WorldEnvironment] and will override the [Camera3D]'s [member Camera3D.far], [member Camera3D.near], [member Camera3D.fov], and [member Camera3D.keep_aspect] properties. When used in [VoxelGI] or [LightmapGI], only the exposure settings will be used. | ||
| The default settings are intended for use in an outdoor environment, tips for settings for use in an indoor environment can be found in each setting's documentation. |
There was a problem hiding this comment.
Technically this should be a semicolon or a period. Also, maybe...?
| The default settings are intended for use in an outdoor environment, tips for settings for use in an indoor environment can be found in each setting's documentation. | |
| The default values are intended for use in an outdoor environment; tips for values to use in an indoor environment can be found in each setting's documentation. |
2 participants
Minor cases with confusion over
it's,its, and the possessive.Obvious cases like
it'sanditsaside and clear mistakes with possessive instead of plural there's a few cases of possessive for singulars ending inswhere'sis generally added (and is in other parts of the docs, so this normalizes this, though there's no absolute rule for this case and just the'is also correct in this case)