From c7eb3d25e7915bda4db0e91deb75d6be744aff06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= Date: Tue, 5 Oct 2021 14:24:34 +0200 Subject: [PATCH] doc: Fix style inconsistencies for `[b]Note:[/b]` paragraphs (cherry picked from commit 788b3aa27ac01263b2e70190ace6551504e0c81e) --- doc/classes/AESContext.xml | 4 ++-- doc/classes/AnimationPlayer.xml | 2 +- doc/classes/AnimationTree.xml | 3 ++- doc/classes/Array.xml | 2 +- doc/classes/ColorPicker.xml | 2 +- doc/classes/ConcavePolygonShape.xml | 2 +- doc/classes/Crypto.xml | 4 ++-- doc/classes/CryptoKey.xml | 4 ++-- doc/classes/DTLSServer.xml | 2 +- doc/classes/EditorResourcePreview.xml | 4 ++-- doc/classes/ImageTexture.xml | 2 +- doc/classes/JavaScriptObject.xml | 2 +- doc/classes/Material.xml | 4 ++-- doc/classes/PacketPeerUDP.xml | 6 +++--- doc/classes/Portal.xml | 6 +++--- doc/classes/RayCast2D.xml | 2 +- doc/classes/ReflectionProbe.xml | 2 +- doc/classes/ShaderMaterial.xml | 3 ++- doc/classes/SpatialMaterial.xml | 4 ++-- doc/classes/StreamPeer.xml | 4 ++-- doc/classes/Timer.xml | 2 +- doc/classes/TouchScreenButton.xml | 2 +- doc/classes/VisualServer.xml | 3 ++- modules/enet/doc_classes/NetworkedMultiplayerENet.xml | 2 +- modules/gdnative/doc_classes/NativeScript.xml | 2 +- modules/webrtc/doc_classes/WebRTCPeerConnection.xml | 3 ++- 26 files changed, 41 insertions(+), 37 deletions(-) diff --git a/doc/classes/AESContext.xml b/doc/classes/AESContext.xml index cb445467880..14498d86712 100644 --- a/doc/classes/AESContext.xml +++ b/doc/classes/AESContext.xml @@ -50,7 +50,7 @@ Get the current IV state for this context (IV gets updated when calling [method update]). You normally don't need this function. - Note: This function only makes sense when the context is started with [constant MODE_CBC_ENCRYPT] or [constant MODE_CBC_DECRYPT]. + [b]Note:[/b] This function only makes sense when the context is started with [constant MODE_CBC_ENCRYPT] or [constant MODE_CBC_DECRYPT]. @@ -67,7 +67,7 @@ Run the desired operation for this AES context. Will return a [PoolByteArray] containing the result of encrypting (or decrypting) the given [code]src[/code]. See [method start] for mode of operation. - Note: The size of [code]src[/code] must be a multiple of 16. Apply some padding if needed. + [b]Note:[/b] The size of [code]src[/code] must be a multiple of 16. Apply some padding if needed. diff --git a/doc/classes/AnimationPlayer.xml b/doc/classes/AnimationPlayer.xml index d7d2181c03c..ca48dbb44e7 100644 --- a/doc/classes/AnimationPlayer.xml +++ b/doc/classes/AnimationPlayer.xml @@ -188,7 +188,7 @@ The name of the currently playing animation. If no animation is playing, the property's value is an empty string. Changing this value does not restart the animation. See [method play] for more information on playing animations. - [b]Note[/b]: while this property appears in the inspector, it's not meant to be edited, and it's not saved in the scene. This property is mainly used to get the currently playing animation, and internally for animation playback tracks. For more information, see [Animation]. + [b]Note:[/b] While this property appears in the inspector, it's not meant to be edited, and it's not saved in the scene. This property is mainly used to get the currently playing animation, and internally for animation playback tracks. For more information, see [Animation]. The length (in seconds) of the currently being played animation. diff --git a/doc/classes/AnimationTree.xml b/doc/classes/AnimationTree.xml index f31eea0e118..282ff12a3e8 100644 --- a/doc/classes/AnimationTree.xml +++ b/doc/classes/AnimationTree.xml @@ -4,7 +4,8 @@ A node to be used for advanced animation transitions in an [AnimationPlayer]. - Note: When linked with an [AnimationPlayer], several properties and methods of the corresponding [AnimationPlayer] will not function as expected. Playback and transitions should be handled using only the [AnimationTree] and its constituent [AnimationNode](s). The [AnimationPlayer] node should be used solely for adding, deleting, and editing animations. + A node to be used for advanced animation transitions in an [AnimationPlayer]. + [b]Note:[/b] When linked with an [AnimationPlayer], several properties and methods of the corresponding [AnimationPlayer] will not function as expected. Playback and transitions should be handled using only the [AnimationTree] and its constituent [AnimationNode](s). The [AnimationPlayer] node should be used solely for adding, deleting, and editing animations. https://docs.godotengine.org/en/3.4/tutorials/animation/animation_tree.html diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml index de600cfecc1..64bf979090c 100644 --- a/doc/classes/Array.xml +++ b/doc/classes/Array.xml @@ -345,7 +345,7 @@ Sorts the array using a custom method. The arguments are an object that holds the method and the name of such method. The custom method receives two arguments (a pair of elements from the array) and must return either [code]true[/code] or [code]false[/code]. For two elements [code]a[/code] and [code]b[/code], if the given method returns [code]true[/code], element [code]b[/code] will be after element [code]a[/code] in the array. - [b]Note:[/b] you cannot randomize the return value as the heapsort algorithm expects a deterministic result. Doing so will result in unexpected behavior. + [b]Note:[/b] You cannot randomize the return value as the heapsort algorithm expects a deterministic result. Doing so will result in unexpected behavior. [codeblock] class MyCustomSorter: static func sort_ascending(a, b): diff --git a/doc/classes/ColorPicker.xml b/doc/classes/ColorPicker.xml index cbda49a9417..e0201446464 100644 --- a/doc/classes/ColorPicker.xml +++ b/doc/classes/ColorPicker.xml @@ -16,7 +16,7 @@ Adds the given color to a list of color presets. The presets are displayed in the color picker and the user will be able to select them. - [b]Note:[/b] the presets list is only for [i]this[/i] color picker. + [b]Note:[/b] The presets list is only for [i]this[/i] color picker. diff --git a/doc/classes/ConcavePolygonShape.xml b/doc/classes/ConcavePolygonShape.xml index 6473c45f089..6718e4797ce 100644 --- a/doc/classes/ConcavePolygonShape.xml +++ b/doc/classes/ConcavePolygonShape.xml @@ -5,7 +5,7 @@ Concave polygon shape resource, which can be set into a [PhysicsBody] or area. This shape is created by feeding a list of triangles. - Note: when used for collision, [ConcavePolygonShape] is intended to work with static [PhysicsBody] nodes like [StaticBody] and will not work with [KinematicBody] or [RigidBody] with a mode other than Static. + [b]Note:[/b] When used for collision, [ConcavePolygonShape] is intended to work with static [PhysicsBody] nodes like [StaticBody] and will not work with [KinematicBody] or [RigidBody] with a mode other than Static. https://godotengine.org/asset-library/asset/675 diff --git a/doc/classes/Crypto.xml b/doc/classes/Crypto.xml index dd76cf55950..eddd2a2be32 100644 --- a/doc/classes/Crypto.xml +++ b/doc/classes/Crypto.xml @@ -54,7 +54,7 @@ Decrypt the given [code]ciphertext[/code] with the provided private [code]key[/code]. - [b]Note[/b]: The maximum size of accepted ciphertext is limited by the key size. + [b]Note:[/b] The maximum size of accepted ciphertext is limited by the key size. @@ -63,7 +63,7 @@ Encrypt the given [code]plaintext[/code] with the provided public [code]key[/code]. - [b]Note[/b]: The maximum size of accepted plaintext is limited by the key size. + [b]Note:[/b] The maximum size of accepted plaintext is limited by the key size. diff --git a/doc/classes/CryptoKey.xml b/doc/classes/CryptoKey.xml index 42f3afb62e4..05e03684763 100644 --- a/doc/classes/CryptoKey.xml +++ b/doc/classes/CryptoKey.xml @@ -23,7 +23,7 @@ Loads a key from [code]path[/code]. If [code]public_only[/code] is [code]true[/code], only the public key will be loaded. - [b]Note[/b]: [code]path[/code] should should be a "*.pub" file if [code]public_only[/code] is [code]true[/code], a "*.key" file otherwise. + [b]Note:[/b] [code]path[/code] should be a "*.pub" file if [code]public_only[/code] is [code]true[/code], a "*.key" file otherwise. @@ -40,7 +40,7 @@ Saves a key to the given [code]path[/code]. If [code]public_only[/code] is [code]true[/code], only the public key will be saved. - [b]Note[/b]: [code]path[/code] should should be a "*.pub" file if [code]public_only[/code] is [code]true[/code], a "*.key" file otherwise. + [b]Note:[/b] [code]path[/code] should be a "*.pub" file if [code]public_only[/code] is [code]true[/code], a "*.key" file otherwise. diff --git a/doc/classes/DTLSServer.xml b/doc/classes/DTLSServer.xml index 20e97144784..6971762d4f0 100644 --- a/doc/classes/DTLSServer.xml +++ b/doc/classes/DTLSServer.xml @@ -75,7 +75,7 @@ Try to initiate the DTLS handshake with the given [code]udp_peer[/code] which must be already connected (see [method PacketPeerUDP.connect_to_host]). - [b]Note[/b]: You must check that the state of the return PacketPeerUDP is [constant PacketPeerDTLS.STATUS_HANDSHAKING], as it is normal that 50% of the new connections will be invalid due to cookie exchange. + [b]Note:[/b] You must check that the state of the return PacketPeerUDP is [constant PacketPeerDTLS.STATUS_HANDSHAKING], as it is normal that 50% of the new connections will be invalid due to cookie exchange. diff --git a/doc/classes/EditorResourcePreview.xml b/doc/classes/EditorResourcePreview.xml index 93154ab3d5a..86097607662 100644 --- a/doc/classes/EditorResourcePreview.xml +++ b/doc/classes/EditorResourcePreview.xml @@ -32,7 +32,7 @@ Queue the [code]resource[/code] being edited for preview. Once the preview is ready, the [code]receiver[/code]'s [code]receiver_func[/code] will be called. The [code]receiver_func[/code] must take the following four arguments: [String] path, [Texture] preview, [Texture] thumbnail_preview, [Variant] userdata. [code]userdata[/code] can be anything, and will be returned when [code]receiver_func[/code] is called. - [b]Note[/b]: If it was not possible to create the preview the [code]receiver_func[/code] will still be called, but the preview will be null. + [b]Note:[/b] If it was not possible to create the preview the [code]receiver_func[/code] will still be called, but the preview will be null. @@ -43,7 +43,7 @@ Queue a resource file located at [code]path[/code] for preview. Once the preview is ready, the [code]receiver[/code]'s [code]receiver_func[/code] will be called. The [code]receiver_func[/code] must take the following four arguments: [String] path, [Texture] preview, [Texture] thumbnail_preview, [Variant] userdata. [code]userdata[/code] can be anything, and will be returned when [code]receiver_func[/code] is called. - [b]Note[/b]: If it was not possible to create the preview the [code]receiver_func[/code] will still be called, but the preview will be null. + [b]Note:[/b] If it was not possible to create the preview the [code]receiver_func[/code] will still be called, but the preview will be null. diff --git a/doc/classes/ImageTexture.xml b/doc/classes/ImageTexture.xml index 4a6811f146e..48717f95406 100644 --- a/doc/classes/ImageTexture.xml +++ b/doc/classes/ImageTexture.xml @@ -61,7 +61,7 @@ Loads an image from a file path and creates a texture from it. - [b]Note:[/b] the method is deprecated and will be removed in Godot 4.0, use [method Image.load] and [method create_from_image] instead. + [b]Note:[/b] This method is deprecated and will be removed in Godot 4.0, use [method Image.load] and [method create_from_image] instead. diff --git a/doc/classes/JavaScriptObject.xml b/doc/classes/JavaScriptObject.xml index 8849c952892..939e5889b83 100644 --- a/doc/classes/JavaScriptObject.xml +++ b/doc/classes/JavaScriptObject.xml @@ -31,7 +31,7 @@ # [0, 9, [JavaScriptObject:1180]] print(args) [/codeblock] - Note: Only available in the "HTML5" platform. + [b]Note:[/b] Only available in the HTML5 platform. diff --git a/doc/classes/Material.xml b/doc/classes/Material.xml index cc6c6d490a2..352c1f9ef77 100644 --- a/doc/classes/Material.xml +++ b/doc/classes/Material.xml @@ -15,11 +15,11 @@ Sets the [Material] to be used for the next pass. This renders the object again using a different material. - [b]Note:[/b] only applies to [SpatialMaterial]s and [ShaderMaterial]s with type "Spatial". + [b]Note:[/b] This only applies to [SpatialMaterial]s and [ShaderMaterial]s with type "Spatial". Sets the render priority for transparent objects in 3D scenes. Higher priority objects will be sorted in front of lower priority objects. - [b]Note:[/b] this only applies to sorting of transparent objects. This will not impact how transparent objects are sorted relative to opaque objects. This is because opaque objects are not sorted, while transparent objects are sorted from back to front (subject to priority). + [b]Note:[/b] This only applies to sorting of transparent objects. This will not impact how transparent objects are sorted relative to opaque objects. This is because opaque objects are not sorted, while transparent objects are sorted from back to front (subject to priority). diff --git a/doc/classes/PacketPeerUDP.xml b/doc/classes/PacketPeerUDP.xml index 2ebebd0cadd..24028dfd850 100644 --- a/doc/classes/PacketPeerUDP.xml +++ b/doc/classes/PacketPeerUDP.xml @@ -55,7 +55,7 @@ Joins the multicast group specified by [code]multicast_address[/code] using the interface identified by [code]interface_name[/code]. You can join the same multicast group with multiple interfaces. Use [method IP.get_local_interfaces] to know which are available. - Note: Some Android devices might require the [code]CHANGE_WIFI_MULTICAST_STATE[/code] permission for multicast to work. + [b]Note:[/b] Some Android devices might require the [code]CHANGE_WIFI_MULTICAST_STATE[/code] permission for multicast to work. @@ -83,7 +83,7 @@ Enable or disable sending of broadcast packets (e.g. [code]set_dest_address("255.255.255.255", 4343)[/code]. This option is disabled by default. - Note: Some Android devices might require the [code]CHANGE_WIFI_MULTICAST_STATE[/code] permission and this option to be enabled to receive broadcast packets too. + [b]Note:[/b] Some Android devices might require the [code]CHANGE_WIFI_MULTICAST_STATE[/code] permission and this option to be enabled to receive broadcast packets too. @@ -92,7 +92,7 @@ Sets the destination address and port for sending packets and variables. A hostname will be resolved using DNS if needed. - Note: [method set_broadcast_enabled] must be enabled before sending packets to a broadcast address (e.g. [code]255.255.255.255[/code]). + [b]Note:[/b] [method set_broadcast_enabled] must be enabled before sending packets to a broadcast address (e.g. [code]255.255.255.255[/code]). diff --git a/doc/classes/Portal.xml b/doc/classes/Portal.xml index 9dd6f967ec3..3e1a6e62239 100644 --- a/doc/classes/Portal.xml +++ b/doc/classes/Portal.xml @@ -27,8 +27,8 @@ The points defining the shape of the [Portal] polygon (which should be convex). - These are defined in 2D, with [code]0,0[/code] being the origin of the [Portal] node's [code]global_transform[/code]. - [code]Note:[/code] These raw points are sanitized for winding order internally. + These are defined in 2D, with [code]0,0[/code] being the origin of the [Portal] node's [member Spatial.global_transform]. + [b]Note:[/b] These raw points are sanitized for winding order internally. Visibility through [Portal]s can be turned on and off at runtime - this is useful for having closable doors. @@ -41,7 +41,7 @@ In most cases you will want to use the default [Portal] margin in your portals (this is set in the [RoomManager]). - If you want to override this default, set this value to [code]false[/code], and the local [code]portal_margin[/code] will take effect. + If you want to override this default, set this value to [code]false[/code], and the local [member portal_margin] will take effect. diff --git a/doc/classes/RayCast2D.xml b/doc/classes/RayCast2D.xml index f002af4430e..2ca0c924a20 100644 --- a/doc/classes/RayCast2D.xml +++ b/doc/classes/RayCast2D.xml @@ -70,7 +70,7 @@ Returns the collision point at which the ray intersects the closest object. - [b]Note:[/b] this point is in the [b]global[/b] coordinate system. + [b]Note:[/b] This point is in the [b]global[/b] coordinate system. diff --git a/doc/classes/ReflectionProbe.xml b/doc/classes/ReflectionProbe.xml index e60bca75939..3581ca545d9 100644 --- a/doc/classes/ReflectionProbe.xml +++ b/doc/classes/ReflectionProbe.xml @@ -6,7 +6,7 @@ Capture its surroundings as a dual paraboloid image, and stores versions of it with increasing levels of blur to simulate different material roughnesses. The [ReflectionProbe] is used to create high-quality reflections at the cost of performance. It can be combined with [GIProbe]s and Screen Space Reflections to achieve high quality reflections. [ReflectionProbe]s render all objects within their [member cull_mask], so updating them can be quite expensive. It is best to update them once with the important static objects and then leave them. - Note: By default Godot will only render 16 reflection probes. If you need more, increase the number of atlas subdivisions. This setting can be found in [member ProjectSettings.rendering/quality/reflections/atlas_subdiv]. + [b]Note:[/b] By default Godot will only render 16 reflection probes. If you need more, increase the number of atlas subdivisions. This setting can be found in [member ProjectSettings.rendering/quality/reflections/atlas_subdiv]. https://docs.godotengine.org/en/3.4/tutorials/3d/reflection_probes.html diff --git a/doc/classes/ShaderMaterial.xml b/doc/classes/ShaderMaterial.xml index 0541381c582..9d3cdd3fb85 100644 --- a/doc/classes/ShaderMaterial.xml +++ b/doc/classes/ShaderMaterial.xml @@ -37,7 +37,8 @@ - Changes the value set for this material of a uniform in the shader. [b]Note:[/b] [code]param[/code] must match the name of the uniform in the code exactly. + Changes the value set for this material of a uniform in the shader. + [b]Note:[/b] [code]param[/code] must match the name of the uniform in the code exactly. diff --git a/doc/classes/SpatialMaterial.xml b/doc/classes/SpatialMaterial.xml index 0a63ead6831..206c6bfa60a 100644 --- a/doc/classes/SpatialMaterial.xml +++ b/doc/classes/SpatialMaterial.xml @@ -199,7 +199,7 @@ If [code]true[/code], render point size can be changed. - [b]Note:[/b] this is only effective for objects whose geometry is point-based rather than triangle-based. See also [member params_point_size]. + [b]Note:[/b] This is only effective for objects whose geometry is point-based rather than triangle-based. See also [member params_point_size]. If [code]true[/code], enables the "shadow to opacity" render mode where lighting modifies the alpha so shadowed areas are opaque and non-shadowed areas are transparent. Useful for overlaying shadows onto a camera feed in AR. @@ -215,7 +215,7 @@ Sets the size of the specular lobe. The specular lobe is the bright spot that is reflected from light sources. - [b]Note:[/b] unlike [member metallic], this is not energy-conserving, so it should be left at [code]0.5[/code] in most cases. See also [member roughness]. + [b]Note:[/b] Unlike [member metallic], this is not energy-conserving, so it should be left at [code]0.5[/code] in most cases. See also [member roughness]. Texture used to specify metallic for an object. This is multiplied by [member metallic]. diff --git a/doc/classes/StreamPeer.xml b/doc/classes/StreamPeer.xml index 258072f30e4..c5274a1c14f 100644 --- a/doc/classes/StreamPeer.xml +++ b/doc/classes/StreamPeer.xml @@ -172,7 +172,7 @@ Puts a zero-terminated ASCII string into the stream prepended by a 32-bit unsigned integer representing its size. - Note: To put an ASCII string without prepending its size, you can use [method put_data]: + [b]Note:[/b] To put an ASCII string without prepending its size, you can use [method put_data]: [codeblock] put_data("Hello world".to_ascii()) [/codeblock] @@ -211,7 +211,7 @@ Puts a zero-terminated UTF-8 string into the stream prepended by a 32 bits unsigned integer representing its size. - Note: To put an UTF-8 string without prepending its size, you can use [method put_data]: + [b]Note:[/b] To put an UTF-8 string without prepending its size, you can use [method put_data]: [codeblock] put_data("Hello world".to_utf8()) [/codeblock] diff --git a/doc/classes/Timer.xml b/doc/classes/Timer.xml index 535d62f1a0d..bc5970bf148 100644 --- a/doc/classes/Timer.xml +++ b/doc/classes/Timer.xml @@ -22,7 +22,7 @@ Starts the timer. Sets [code]wait_time[/code] to [code]time_sec[/code] if [code]time_sec > 0[/code]. This also resets the remaining time to [code]wait_time[/code]. - [b]Note:[/b] this method will not resume a paused timer. See [member paused]. + [b]Note:[/b] This method will not resume a paused timer. See [member paused]. diff --git a/doc/classes/TouchScreenButton.xml b/doc/classes/TouchScreenButton.xml index 3a8149b008a..688e286bac5 100644 --- a/doc/classes/TouchScreenButton.xml +++ b/doc/classes/TouchScreenButton.xml @@ -30,7 +30,7 @@ If [code]true[/code], the [signal pressed] and [signal released] signals are emitted whenever a pressed finger goes in and out of the button, even if the pressure started outside the active area of the button. - [b]Note:[/b] this is a "pass-by" (not "bypass") press mode. + [b]Note:[/b] This is a "pass-by" (not "bypass") press mode. The button's texture for the pressed state. diff --git a/doc/classes/VisualServer.xml b/doc/classes/VisualServer.xml index 87b1f8fd9f0..f6cb6d4a146 100644 --- a/doc/classes/VisualServer.xml +++ b/doc/classes/VisualServer.xml @@ -2317,7 +2317,8 @@ - Sets the material for processing the particles. Note: this is not the material used to draw the materials. Equivalent to [member Particles.process_material]. + Sets the material for processing the particles. + [b]Note:[/b] This is not the material used to draw the materials. Equivalent to [member Particles.process_material]. diff --git a/modules/enet/doc_classes/NetworkedMultiplayerENet.xml b/modules/enet/doc_classes/NetworkedMultiplayerENet.xml index 8acdb1da721..e8d3957fb35 100644 --- a/modules/enet/doc_classes/NetworkedMultiplayerENet.xml +++ b/modules/enet/doc_classes/NetworkedMultiplayerENet.xml @@ -137,7 +137,7 @@ When enabled, the client or server created by this peer, will use [PacketPeerDTLS] instead of raw UDP sockets for communicating with the remote peer. This will make the communication encrypted with DTLS at the cost of higher resource usage and potentially larger packet size. - Note: When creating a DTLS server, make sure you setup the key/certificate pair via [method set_dtls_key] and [method set_dtls_certificate]. For DTLS clients, have a look at the [member dtls_verify] option, and configure the certificate accordingly via [method set_dtls_certificate]. + [b]Note:[/b] When creating a DTLS server, make sure you setup the key/certificate pair via [method set_dtls_key] and [method set_dtls_certificate]. For DTLS clients, have a look at the [member dtls_verify] option, and configure the certificate accordingly via [method set_dtls_certificate]. diff --git a/modules/gdnative/doc_classes/NativeScript.xml b/modules/gdnative/doc_classes/NativeScript.xml index b9c30aa963a..871bd9618f2 100644 --- a/modules/gdnative/doc_classes/NativeScript.xml +++ b/modules/gdnative/doc_classes/NativeScript.xml @@ -38,7 +38,7 @@ Constructs a new object of the base type with a script of this type already attached. - [i]Note[/i]: Any arguments passed to this function will be ignored and not passed to the native constructor function. This will change with in a future API extension. + [b]Note:[/b] Any arguments passed to this function will be ignored and not passed to the native constructor function. This will change with in a future API extension. diff --git a/modules/webrtc/doc_classes/WebRTCPeerConnection.xml b/modules/webrtc/doc_classes/WebRTCPeerConnection.xml index def76873a4f..949108d3a98 100644 --- a/modules/webrtc/doc_classes/WebRTCPeerConnection.xml +++ b/modules/webrtc/doc_classes/WebRTCPeerConnection.xml @@ -26,7 +26,8 @@ - Close the peer connection and all data channels associated with it. Note, you cannot reuse this object for a new connection unless you call [method initialize]. + Close the peer connection and all data channels associated with it. + [b]Note:[/b] You cannot reuse this object for a new connection unless you call [method initialize].