Merge pull request #10756 from Repiteo/style/pragma-once

Style: Integrate new `#pragma once` syntax

contributing/development/code_style_guidelines.rst

@@ -203,8 +203,7 @@ Example:
     /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
     /**************************************************************************/
 
-    #ifndef MY_NEW_FILE_H
-    #define MY_NEW_FILE_H
+    #pragma once
 
     #include "core/hash_map.h"
     #include "core/list.h"
@@ -212,10 +211,6 @@ Example:
 
     #include <png.h>
 
-    ...
-
-    #endif // MY_NEW_FILE_H
-
 .. code-block:: cpp
     :caption: my_new_file.cpp
 

contributing/development/core_and_modules/binding_to_external_libraries.rst

@@ -22,8 +22,7 @@ Next, you will create a header file with a TTS class:
 .. code-block:: cpp
     :caption: godot/modules/tts/tts.h
 
-    #ifndef GODOT_TTS_H
-    #define GODOT_TTS_H
+    #pragma once
 
     #include "core/object/ref_counted.h"
 
@@ -39,8 +38,6 @@ Next, you will create a header file with a TTS class:
         TTS();
     };
 
-    #endif // GODOT_TTS_H
-
 And then you'll add the cpp file.
 
 .. code-block:: cpp

contributing/development/core_and_modules/custom_godot_servers.rst

@@ -41,8 +41,7 @@ an initialization state and a cleanup procedure.
 .. code-block:: cpp
     :caption: hilbert_hotel.h
 
-    #ifndef HILBERT_HOTEL_H
-    #define HILBERT_HOTEL_H
+    #pragma once
 
     #include "core/object/object.h"
     #include "core/os/thread.h"
@@ -91,8 +90,6 @@ an initialization state and a cleanup procedure.
         HilbertHotel();
     };
 
-    #endif
-
 .. code-block:: cpp
     :caption: hilbert_hotel.cpp
 

contributing/development/core_and_modules/custom_modules_in_cpp.rst

@@ -47,8 +47,7 @@ Inside we will create a summator class:
 .. code-block:: cpp
     :caption: godot/modules/summator/summator.h
 
-    #ifndef SUMMATOR_H
-    #define SUMMATOR_H
+    #pragma once
 
     #include "core/object/ref_counted.h"
 
@@ -68,8 +67,6 @@ Inside we will create a summator class:
         Summator();
     };
 
-    #endif // SUMMATOR_H
-
 And then the cpp file.
 
 .. code-block:: cpp
@@ -621,8 +618,7 @@ The procedure is the following:
 .. code-block:: cpp
     :caption: godot/modules/summator/tests/test_summator.h
 
-    #ifndef TEST_SUMMATOR_H
-    #define TEST_SUMMATOR_H
+    #pragma once
 
     #include "tests/test_macros.h"
 
@@ -649,8 +645,6 @@ The procedure is the following:
 
     } // namespace TestSummator
 
-    #endif // TEST_SUMMATOR_H
-
 4. Compile the engine with ``scons tests=yes``, and run the tests with the
    following command:
 

contributing/development/core_and_modules/custom_resource_format_loaders.rst

@@ -58,8 +58,7 @@ read and handle data serialization.
 .. code-block:: cpp
     :caption: resource_loader_json.h
 
-    #ifndef RESOURCE_LOADER_JSON_H
-    #define RESOURCE_LOADER_JSON_H
+    #pragma once
 
     #include "core/io/resource_loader.h"
 
@@ -71,7 +70,6 @@ read and handle data serialization.
         virtual bool handles_type(const String &p_type) const;
         virtual String get_resource_type(const String &p_path) const;
     };
-    #endif // RESOURCE_LOADER_JSON_H
 
 .. code-block:: cpp
     :caption: resource_loader_json.cpp
@@ -112,8 +110,7 @@ If you'd like to be able to edit and save a resource, you can implement a
 .. code-block:: cpp
     :caption: resource_saver_json.h
 
-    #ifndef RESOURCE_SAVER_JSON_H
-    #define RESOURCE_SAVER_JSON_H
+    #pragma once
 
     #include "core/io/resource_saver.h"
 
@@ -124,7 +121,6 @@ If you'd like to be able to edit and save a resource, you can implement a
         virtual bool recognize(const RES &p_resource) const;
         virtual void get_recognized_extensions(const RES &p_resource, List<String> *r_extensions) const;
     };
-    #endif // RESOURCE_SAVER_JSON_H
 
 .. code-block:: cpp
     :caption: resource_saver_json.cpp
@@ -162,8 +158,7 @@ Here is an example of creating a custom datatype:
 .. code-block:: cpp
     :caption: resource_json.h
 
-    #ifndef RESOURCE_JSON_H
-    #define RESOURCE_JSON_H
+    #pragma once
 
     #include "core/io/json.h"
     #include "core/variant_parser.h"
@@ -189,7 +184,6 @@ Here is an example of creating a custom datatype:
         void set_dict(const Dictionary &p_dict);
         Dictionary get_dict();
     };
-    #endif // RESOURCE_JSON_H
 
 .. code-block:: cpp
     :caption: resource_json.cpp

contributing/development/core_and_modules/unit_testing.rst

@@ -113,8 +113,7 @@ Here's a minimal working test suite with a single test case written:
 
 .. code-block:: cpp
 
-    #ifndef TEST_STRING_H
-    #define TEST_STRING_H
+    #pragma once
 
     #include "tests/test_macros.h"
 
@@ -127,8 +126,6 @@ Here's a minimal working test suite with a single test case written:
 
     } // namespace TestString
 
-    #endif // TEST_STRING_H
-
 .. note::
     You can quickly generate new tests using the ``create_test.py`` script found in the ``tests/`` directory.
     This script automatically creates a new test file with the required boilerplate code in the appropriate location.

contributing/development/cpp_usage_guidelines.rst

@@ -112,11 +112,12 @@ Lambdas should be used conservatively when they make code effectively faster or
 simpler, and do not impede readability. Please ask before using lambdas in a
 pull request.
 
-``#pragma once`` directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+``#ifdef``-based include guards
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To follow the existing style, please use standard ``#ifdef``-based include
-guards instead of ``#pragma once`` in new files.
+Starting with 4.5, all files now use the ``#pragma once`` directive, as they
+improve readability and declutter macros. Use of ``#ifdef``-based include
+guards are now actively discouraged.
 
 ``try``-``catch`` blocks
 ~~~~~~~~~~~~~~~~~~~~~~~~

tutorials/performance/using_multiple_threads.rst

@@ -49,8 +49,7 @@ To create a thread, use the following code:
 
  .. code-tab:: cpp C++ .H File
 
-    #ifndef MULTITHREADING_DEMO_H
-    #define MULTITHREADING_DEMO_H
+    #pragma once
 
     #include <godot_cpp/classes/node.hpp>
     #include <godot_cpp/classes/thread.hpp>
@@ -74,8 +73,6 @@ To create a thread, use the following code:
         };
     } // namespace godot
 
-    #endif // MULTITHREADING_DEMO_H
-
  .. code-tab:: cpp C++ .CPP File
 
     #include "multithreading_demo.h"
@@ -209,8 +206,7 @@ Here is an example of using a Mutex:
 
  .. code-tab:: cpp C++ .H File
 
-    #ifndef MUTEX_DEMO_H
-    #define MUTEX_DEMO_H
+    #pragma once
 
     #include <godot_cpp/classes/mutex.hpp>
     #include <godot_cpp/classes/node.hpp>
@@ -237,8 +233,6 @@ Here is an example of using a Mutex:
         };
     } // namespace godot
 
-    #endif // MUTEX_DEMO_H
-
  .. code-tab:: cpp C++ .CPP File
 
     #include "mutex_demo.h"
@@ -379,8 +373,7 @@ ready to be processed:
 
  .. code-tab:: cpp C++ .H File
 
-    #ifndef SEMAPHORE_DEMO_H
-    #define SEMAPHORE_DEMO_H
+    #pragma once
 
     #include <godot_cpp/classes/mutex.hpp>
     #include <godot_cpp/classes/node.hpp>
@@ -412,8 +405,6 @@ ready to be processed:
         };
     } // namespace godot
 
-    #endif // SEMAPHORE_DEMO_H
-
  .. code-tab:: cpp C++ .CPP File
 
     #include "semaphore_demo.h"

tutorials/scripting/gdextension/gdextension_c_example.rst

@@ -133,8 +133,7 @@ Create the file ``init.h`` in the ``src`` folder, with the following contents:
 
 .. code-block:: c
 
-    #ifndef INIT_H
-    #define INIT_H
+    #pragma once
 
     #include "defs.h"
 
@@ -144,8 +143,6 @@ Create the file ``init.h`` in the ``src`` folder, with the following contents:
     void deinitialize_gdexample_module(void *p_userdata, GDExtensionInitializationLevel p_level);
     GDExtensionBool GDE_EXPORT gdexample_library_init(GDExtensionInterfaceGetProcAddress p_get_proc_address, GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization);
 
-    #endif // INIT_H
-
 The functions declared here have the signatures expected by the GDExtension API.
 
 Note the inclusion of the ``defs.h`` file. This is one of our helpers to
@@ -158,8 +155,7 @@ Create the ``defs.h`` file in the ``src`` folder with the following contents:
 
 .. code-block:: c
 
-    #ifndef DEFS_H
-    #define DEFS_H
+    #pragma once
 
     #include <stdbool.h>
     #include <stddef.h>
@@ -175,8 +171,6 @@ Create the ``defs.h`` file in the ``src`` folder with the following contents:
     #endif
     #endif // ! GDE_EXPORT
 
-    #endif // DEFS_H
-
 We also include some standard headers to make things easier. Now we only have to
 include ``defs.h`` and those will come as a bonus.
 
@@ -224,8 +218,7 @@ contents:
 
 .. code-block:: c
 
-    #ifndef GDEXAMPLE_H
-    #define GDEXAMPLE_H
+    #pragma once
 
     #include "gdextension_interface.h"
 
@@ -247,8 +240,6 @@ contents:
     // Bindings.
     void gdexample_class_bind_methods();
 
-    #endif // GDEXAMPLE_H
-
 Noteworthy here is the ``object`` field, which holds a pointer to
 the Godot object, and the ``gdexample_class_bind_methods()`` function, which will
 register the metadata of our custom class (properties, methods, and signals).
@@ -299,8 +290,7 @@ We'll start by creating an ``api.h`` file in the ``src`` folder:
 
 .. code-block:: c
 
-    #ifndef API_H
-    #define API_H
+    #pragma once
 
     /*
     This file works as a collection of helpers to call the GDExtension API
@@ -333,10 +323,6 @@ We'll start by creating an ``api.h`` file in the ``src`` folder:
 
     void load_api(GDExtensionInterfaceGetProcAddress p_get_proc_address);
 
-
-
-    #endif // API_H
-
 This file will include many other helpers as we fill our extension with
 something useful. For now it only has a pointer to a function that creates a
 StringName from a C string (in Latin-1 encoding) and another to destruct a

tutorials/scripting/gdextension/gdextension_cpp_example.rst

@@ -164,8 +164,7 @@ GDExtension node we'll be creating. We will name it ``gdexample.h``:
 .. code-block:: cpp
     :caption: gdextension_cpp_example/src/gdexample.h
 
-    #ifndef GDEXAMPLE_H
-    #define GDEXAMPLE_H
+    #pragma once
 
     #include <godot_cpp/classes/sprite2d.hpp>
 
@@ -187,9 +186,7 @@ GDExtension node we'll be creating. We will name it ``gdexample.h``:
         void _process(double delta) override;
     };
 
-    }
-
-    #endif
+    } // namespace godot
 
 There are a few things of note to the above. We include ``sprite2d.hpp`` which
 contains bindings to the Sprite2D class. We'll be extending this class in our
@@ -313,8 +310,7 @@ At last, we need the header file for the ``register_types.cpp`` named
 .. code-block:: cpp
     :caption: gdextension_cpp_example/src/register_types.h
 
-    #ifndef GDEXAMPLE_REGISTER_TYPES_H
-    #define GDEXAMPLE_REGISTER_TYPES_H
+    #pragma once
 
     #include <godot_cpp/core/class_db.hpp>
 
@@ -323,9 +319,6 @@ At last, we need the header file for the ``register_types.cpp`` named
     void initialize_example_module(ModuleInitializationLevel p_level);
     void uninitialize_example_module(ModuleInitializationLevel p_level);
 
-    #endif // GDEXAMPLE_REGISTER_TYPES_H
-
-
 Compiling the plugin
 --------------------