Merge pull request #10243 from tetrapod00/update-comments

mhilbrunner · web-flow · commit 02f5982938e9 · 2024-11-18T13:05:07.000+01:00
Add UPDATE comments to perishable information
diff --git a/about/release_policy.rst b/about/release_policy.rst
@@ -63,6 +63,8 @@ further developed for maintenance releases in a Git branch of the same name
 Release support timeline
 ------------------------
 
+.. UPDATE: Table changes every minor version. Support policy may change.
+
 Stable branches are supported *at least* until the next stable branch is
 released and has received its first patch update. In practice, we support
 stable branches on a *best effort* basis for as long as they have active users
@@ -202,6 +204,8 @@ features that come with 4.0+.
 When is the next release out?
 -----------------------------
 
+.. UPDATE: Refers to specific current minor versions 3.6 and 3.7.
+
 While Godot contributors aren't working under any deadlines, we strive to
 publish minor releases relatively frequently.
 
diff --git a/contributing/development/core_and_modules/internal_rendering_architecture.rst b/contributing/development/core_and_modules/internal_rendering_architecture.rst
@@ -217,6 +217,8 @@ wouldn't have. Both the clustered and mobile
 :ref:`doc_internal_rendering_architecture_methods` can be used with a Metal
 backend via MoltenVK.
 
+.. UPDATE: Planned feature. When the native Metal driver is implemented, update this.
+
 A native Metal driver is planned in the future for better performance and
 compatibility.
 
@@ -395,6 +397,9 @@ allows maximizing the performance of bilinear 3D scaling.
 The ``configure()`` function in RenderSceneBuffersRD reallocates the 2D/3D
 buffers when the resolution or scaling changes.
 
+.. UPDATE: Planned feature. When dynamic resolution scaling is supported,
+.. update this paragraph.
+
 Dynamic resolution scaling isn't supported yet, but is planned in a future Godot
 release.
 
@@ -413,6 +418,9 @@ release.
 2D light rendering is performed in a single pass to allow for better performance
 with large amounts of lights.
 
+.. UPDATE: Planned feature. When Forward+ and Mobile feature 2D batching,
+.. update this.
+
 The Forward+ and Mobile rendering methods don't feature 2D batching yet, but
 it's planned for a future release.
 
@@ -476,6 +484,9 @@ apart so that each object is only touched by 1 or 2 shadowed lights at a time.
 The maximum number of lights visible at once can be adjusted in the project
 settings.
 
+.. UPDATE: Planned feature. When static and dynamic shadow rendering are
+.. separated, update this paragraph.
+
 In all 3 methods, lights without shadows are much cheaper than lights with
 shadows. To improve performance, lights are only updated when the light is
 modified or when objects in its radius are modified. Godot currently doesn't
diff --git a/tutorials/2d/2d_parallax.rst b/tutorials/2d/2d_parallax.rst
@@ -10,6 +10,9 @@ Parallax is an effect used to simulate depth by having textures move at differen
 provides the :ref:`Parallax2D<class_parallax2d>` node to achieve this effect. It can still be easy to get tripped
 up though, so this page provides in-depth descriptions of some properties and how to fix some common mistakes.
 
+.. UPDATE: Experimental. When Parallax2D is no longer experimental, remove this
+.. note and remove this comment.
+
 .. note::
     This page only covers how to use :ref:`Parallax2D<class_parallax2d>`. This node is still experimental, so the
     implementation might change in future versions of Godot. However, it is still recommended to use over the
diff --git a/tutorials/3d/particles/attractors.rst b/tutorials/3d/particles/attractors.rst
@@ -13,6 +13,9 @@ and :ref:`class_GPUParticlesAttractorVectorField3D`. You can instantiate them at
 change their properties from gameplay code; you can even animate and combine them for complex
 attraction effects.
 
+.. UPDATE: Not implemented. When particle attractors are implemented for 2D
+.. particle systems, remove this note and remove this comment.
+
 .. note::
 
    Particle attractors are not yet implemented for 2D particle systems.
diff --git a/tutorials/3d/standard_material_3d.rst b/tutorials/3d/standard_material_3d.rst
@@ -261,6 +261,9 @@ can considerably increase rendering performance.
 Keep in mind that when unshaded rendering is enabled, lights will not affect the
 material at all.
 
+.. UPDATE: Not implemented. When per-vertex shading is implemented, remove this
+.. note and remove this comment.
+
 .. note::
 
     **Per-Vertex** shading is listed as an option in the shading mode property.
diff --git a/tutorials/assets_pipeline/importing_images.rst b/tutorials/assets_pipeline/importing_images.rst
@@ -377,6 +377,9 @@ mipmaps but memory usage will increase.
 Mipmaps > Limit
 ^^^^^^^^^^^^^^^
 
+.. UPDATE: Not implemented. When Mipmaps > Limit is implemented, remove this
+.. warning and remove this comment.
+
 .. warning::
 
     **Mipmaps > Limit** is currently not implemented and has no effect when changed.
diff --git a/tutorials/audio/audio_streams.rst b/tutorials/audio/audio_streams.rst
@@ -33,6 +33,9 @@ AudioStreamPlayer
 This is the standard, non-positional stream player. It can play to any bus.
 In 5.1 sound setups, it can send audio to stereo mix or front speakers.
 
+.. UPDATE: Experimental. When Playback Type is no longer experimental, update
+.. this paragraph.
+
 Playback Type is an experimental setting, and could change in future versions
 of Godot. It exists so Web exports use Web Audio-API based samples instead of
 streaming all sounds to the browser, unlike most platforms. This prevents the
diff --git a/tutorials/editor/using_the_web_editor.rst b/tutorials/editor/using_the_web_editor.rst
@@ -25,6 +25,9 @@ browsers support WebAssembly threading and can therefore run the web editor:
 - Firefox 79 or later
 - Edge 79 or later
 
+.. UPDATE: Not supported yet. When Opera, Safari, or mobile browsers are
+.. supported, update or remove these paragraphs.
+
 Opera and Safari are not supported yet. Safari may work in the future once
 proper threading support is added.
 
@@ -116,6 +119,9 @@ Due to browser security limitations, the editor will save the project files to
 the browser's IndexedDB storage. This storage isn't accessible as a regular folder
 on your machine, but is abstracted away in a database.
 
+.. UPDATE: Not supported yet. When exporting from the web editor is supported,
+.. update this paragraph.
+
 You can download the project files as a ZIP archive by using
 **Project > Tools > Download Project Source**. This can be used to export the
 project using a `native Godot editor <https://godotengine.org/download>`__,
diff --git a/tutorials/export/exporting_for_web.rst b/tutorials/export/exporting_for_web.rst
@@ -235,6 +235,9 @@ player to click, tap or press a key/button to enable audio, for instance when di
 Networking
 ~~~~~~~~~~
 
+.. UPDATE: Not implemented. When low level networking is implemented, remove
+.. this paragraph.
+
 Low level networking is not implemented due to lacking support in browsers.
 
 Currently, only :ref:`HTTP client <doc_http_client_class>`,
diff --git a/tutorials/io/data_paths.rst b/tutorials/io/data_paths.rst
@@ -183,6 +183,9 @@ You can use it to create a portable installation of the editor.
 The `Steam release of Godot <https://store.steampowered.com/app/404790/>`__ uses
 self-contained mode by default.
 
+.. UPDATE: Not supported yet. When self-contained mode is supported in exported
+.. projects, remove or update this note.
+
 .. note::
 
     Self-contained mode is not supported in exported projects yet.
diff --git a/tutorials/math/matrices_and_transforms.rst b/tutorials/math/matrices_and_transforms.rst
@@ -607,6 +607,9 @@ this project which has colored lines and cubes to help visualize the
 :ref:`class_Basis` vectors and the origin in both 2D and 3D:
 https://github.com/godotengine/godot-demo-projects/tree/master/misc/matrix_transform
 
+.. UPDATE: May change in future. When you can edit a Node2D's transform matrix
+.. directly, remove or update this note.
+
 .. note:: You cannot edit Node2D's transform matrix directly in Godot 4.0's
           inspector. This may be changed in a future release of Godot.
 
diff --git a/tutorials/migrating/upgrading_to_godot_4.rst b/tutorials/migrating/upgrading_to_godot_4.rst
@@ -63,6 +63,10 @@ Godot 3.x for the following reasons:
 Caveats of upgrading
 ^^^^^^^^^^^^^^^^^^^^
 
+.. UPDATE: Planned feature. There are several planned or missing features that
+.. may be added back in the future. Check this section for accuracy and update
+.. it if things have changed!
+
 **Since Godot 4 is a complete rewrite in many aspects, some features have
 unfortunately been lost in the process.** Some of these features may be restored
 in future Godot releases:
diff --git a/tutorials/performance/gpu_optimization.rst b/tutorials/performance/gpu_optimization.rst
@@ -155,7 +155,7 @@ Pay attention to the additional vertex processing required when using:
 -  Skinning (skeletal animation)
 -  Morphs (shape keys)
 
-.. Not implemented in Godot 4.x yet. Uncomment when this is implemented.
+.. UPDATE: Not implemented in Godot 4.x yet. Uncomment when this is implemented.
    -  Vertex-lit objects (common on mobile)
 
 Pixel/fragment shaders and fill rate
diff --git a/tutorials/performance/pipeline_compilations.rst b/tutorials/performance/pipeline_compilations.rst
@@ -59,6 +59,8 @@ pipeline recompilations.
 Pipeline precompilation monitors
 --------------------------------
 
+.. UPDATE: Future versions mentioned.
+
 Compiling pipelines ahead of time is the main mechanism Godot uses to mitigate
 shader stutters, but it's not a perfect solution. Being aware of the situations
 that can lead to pipeline stutters can be very helpful, and the workarounds are
diff --git a/tutorials/platform/android/android_plugin.rst b/tutorials/platform/android/android_plugin.rst
@@ -369,6 +369,9 @@ github template for reference on how to do so.
 Godot crashes upon load
 ^^^^^^^^^^^^^^^^^^^^^^^
 
+.. UPDATE: Not supported yet. When more complex datatypes are supported,
+.. update this section.
+
 Check ``adb logcat`` for possible problems, then:
 
 - Check that the methods exposed by the plugin used the following Java types: ``void``, ``boolean``, ``int``, ``float``, ``java.lang.String``, ``org.godotengine.godot.Dictionary``, ``int[]``, ``byte[]``, ``float[]``, ``java.lang.String[]``.
diff --git a/tutorials/rendering/compositor.rst b/tutorials/rendering/compositor.rst
@@ -311,6 +311,9 @@ post processes have run.
 From our internal size we calculate our group size, see our local size in our
 template shader.
 
+.. UPDATE: Not supported yet. When structs are supported here, update this
+.. paragraph.
+
 We also populate our push constant so our shader knows our size.
 Godot does not support structs here **yet** so we use a
 ``PackedFloat32Array`` to store this data into. Note that we have
diff --git a/tutorials/rendering/multiple_resolutions.rst b/tutorials/rendering/multiple_resolutions.rst
@@ -467,6 +467,9 @@ Non-game application
   script's ``_ready()`` function. This prevents the user from resizing the application
   below a certain size, which could break the UI layout.
 
+.. UPDATE: Planned feature. When manually override the 2D scale factor is supported,
+.. update this note.
+
 .. note::
 
     Godot doesn't support manually overriding the 2D scale factor yet, so it is
diff --git a/tutorials/scripting/gdscript/gdscript_exports.rst b/tutorials/scripting/gdscript/gdscript_exports.rst
@@ -389,6 +389,9 @@ The default value **must** be a constant expression.
 
     @export var a = [1, 2, 3]
 
+.. UPDATE: Not supported yet. When nested typed arrays are supported, update
+.. the example.
+
 Exported arrays can specify type (using the same hints as before).
 
 ::
diff --git a/tutorials/scripting/gdscript/static_typing.rst b/tutorials/scripting/gdscript/static_typing.rst
@@ -59,6 +59,8 @@ methods, properties, constants, etc. from the value:
     **Text Editor > Completion > Add Type Hints** editor setting. Also consider
     enabling `some warnings <Warning system_>`_ that are disabled by default.
 
+.. UPDATE: Planned feature. If JIT/AOT are implemented, update this paragraph.
+
 Also, typed GDScript improves performance by using optimized opcodes when operand/argument
 types are known at compile time. More GDScript optimizations are planned in the future,
 such as JIT/AOT compilation.
@@ -481,6 +483,8 @@ finally declare a statically typed variable with the object::
 Cases where you can't specify types
 -----------------------------------
 
+.. UPDATE: Not supported. If nested types are supported, update this section.
+
 To wrap up this introduction, let's mention cases where you can't use type hints.
 This will trigger a **syntax error**.
 
@@ -497,13 +501,12 @@ This will trigger a **syntax error**.
 
         var teams: Array[Array[Character]] = []
 
-3. Typed dictionaries are not currently supported::
-
-        var map: Dictionary[Vector2i, Item] = {}
-
 Summary
 -------
 
+.. UPDATE: Planned feature. If more optimizations (possibly JIT/AOT?) are
+.. implemented, update this paragraph.
+
 Typed GDScript is a powerful tool. It helps you write more structured code,
 avoid common errors, and create scalable and reliable systems. Static types
 improve GDScript performance and more optimizations are planned for the future.
diff --git a/tutorials/troubleshooting.rst b/tutorials/troubleshooting.rst
@@ -211,6 +211,9 @@ tonemapping (as opposed to :abbr:`DTM (Dynamic Tone Mapping)`), then
 It is also strongly recommended to use Windows 11 instead of Windows 10 when using HDR.
 The end result will still likely be inferior to disabling HDR on the display, though.
 
+.. UPDATE: Planned feature. When HDR output is implemented, remove or update
+.. this paragraph.
+
 Support for HDR *output* is planned in a future release.
 
 The editor/project freezes or displays glitched visuals after resuming the PC from suspend
diff --git a/tutorials/xr/setting_up_xr.rst b/tutorials/xr/setting_up_xr.rst
@@ -35,9 +35,15 @@ While in Godot 3 most things worked out of the box, Godot 4 needs a little more
 
 .. image:: img/xr_shaders.png
 
+.. UPDATE: Not supported yet. When all or most post process effects work in
+.. stereoscopic rendering, remove or update this note.
+
 .. warning::
     As Godot 4 is still in development, many post process effects have not yet been updated to support stereoscopic rendering. Using these will have adverse effects.
 
+.. UPDATE: Recommended renderer may change. If the Mobile renderer (or any other
+.. renderer) is recommended for all XR projects, update this note.
+
 .. note::
     Godot 4 has 3 renderer options, Compatibility, Mobile, and Forward+. In the future XR desktop projects should use Forward+, and projects for standalone headsets
     should use Mobile. Currently Compatibility is the recommended renderer for standalone headsets, and ironically Mobile is the recommended renderer for desktop.
