Add filenames as captions for code blocks

contributing/development/core_and_modules/binding_to_external_libraries.rst

@@ -20,8 +20,7 @@ To bind to an external library, set up a module directory similar to the Summato
 Next, you will create a header file with a TTS class:
 
 .. code-block:: cpp
-
-    /* tts.h */
+    :caption: godot/modules/tts/tts.h
 
     #ifndef GODOT_TTS_H
     #define GODOT_TTS_H
@@ -45,8 +44,7 @@ Next, you will create a header file with a TTS class:
 And then you'll add the cpp file.
 
 .. code-block:: cpp
-
-    /* tts.cpp */
+    :caption: godot/modules/tts/tts.cpp
 
     #include "tts.h"
 
@@ -82,16 +80,14 @@ need to be created:
 These files should contain the following:
 
 .. code-block:: cpp
-
-    /* register_types.h */
+    :caption: godot/modules/tts/register_types.h
 
     void initialize_tts_module(ModuleInitializationLevel p_level);
     void uninitialize_tts_module(ModuleInitializationLevel p_level);
     /* yes, the word in the middle must be the same as the module folder name */
 
 .. code-block:: cpp
-
-    /* register_types.cpp */
+    :caption: godot/modules/tts/register_types.cpp
 
     #include "register_types.h"
 
@@ -113,8 +109,7 @@ Next, you need to create an ``SCsub`` file so the build system compiles
 this module:
 
 .. code-block:: python
-
-    # SCsub
+    :caption: godot/modules/tts/SCsub
 
     Import('env')
 
@@ -127,9 +122,9 @@ installation commands for Linux below, for reference.
 
 .. code-block:: shell
 
-    sudo apt-get install festival festival-dev <-- Installs festival and speech_tools libraries
-    apt-cache search festvox-* <-- Displays list of voice packages
-    sudo apt-get install festvox-don festvox-rablpc16k festvox-kallpc16k festvox-kdlpc16k <-- Installs voices
+    sudo apt-get install festival festival-dev  # Installs festival and speech_tools libraries
+    apt-cache search festvox-*  # Displays list of voice packages
+    sudo apt-get install festvox-don festvox-rablpc16k festvox-kallpc16k festvox-kdlpc16k  # Installs voices
 
 .. important::
     The voices that Festival uses (and any other potential external/3rd-party
@@ -165,6 +160,7 @@ To add include directories for the compiler to look at you can append it to the
 environment's paths:
 
 .. code-block:: python
+    :caption: godot/modules/tts/SCsub
 
     # These paths are relative to /modules/tts/
     env_tts.Append(CPPPATH=["speech_tools/include", "festival/src/include"])
@@ -186,8 +182,7 @@ If you want to add custom compiler flags when building your module, you need to
 Example `SCsub` with custom flags:
 
 .. code-block:: python
-
-    # SCsub
+    :caption: godot/modules/tts/SCsub
 
     Import('env')
 

contributing/development/core_and_modules/custom_audiostreams.rst

@@ -46,8 +46,7 @@ object regardless how many times ``load`` is called on a specific resource.
 Therefore, playback state must be self-contained in AudioStreamPlayback.
 
 .. code-block:: cpp
-
-    /* audiostream_mytone.h */
+    :caption: audiostream_mytone.h
 
     #include "core/reference.h"
     #include "core/resource.h"
@@ -77,8 +76,7 @@ Therefore, playback state must be self-contained in AudioStreamPlayback.
     };
 
 .. code-block:: cpp
-
-    /* audiostream_mytone.cpp */
+    :caption: audiostream_mytone.cpp
 
     #include "audiostream_mytone.h"
 
@@ -127,8 +125,7 @@ AudioStreamPlayer uses ``mix`` callback to obtain PCM data. The callback must ma
 Since AudioStreamPlayback is controlled by the audio thread, i/o and dynamic memory allocation are forbidden.
 
 .. code-block:: cpp
-
-    /*  audiostreamplayer_mytone.h */
+    :caption: audiostreamplayer_mytone.h
 
     #include "core/reference.h"
     #include "core/resource.h"
@@ -165,8 +162,7 @@ Since AudioStreamPlayback is controlled by the audio thread, i/o and dynamic mem
     };
 
 .. code-block:: cpp
-
-    /* audiostreamplayer_mytone.cpp */
+    :caption: audiostreamplayer_mytone.cpp
 
     #include "audiostreamplayer_mytone.h"
 
@@ -239,6 +235,7 @@ Instead of overloading ``mix``, AudioStreamPlaybackResampled uses ``_mix_interna
 query AudioFrames and ``get_stream_sampling_rate`` to query current mix rate.
 
 .. code-block:: cpp
+    :caption: mytone_audiostream_resampled.h
 
     #include "core/reference.h"
     #include "core/resource.h"
@@ -280,6 +277,7 @@ query AudioFrames and ``get_stream_sampling_rate`` to query current mix rate.
     };
 
 .. code-block:: cpp
+    :caption: mytone_audiostream_resampled.cpp
 
     #include "mytone_audiostream_resampled.h"
 

contributing/development/core_and_modules/custom_godot_servers.rst

@@ -39,6 +39,7 @@ At minimum, a server must have a static instance, a sleep timer, a thread loop,
 an initialization state and a cleanup procedure.
 
 .. code-block:: cpp
+    :caption: hilbert_hotel.h
 
     #ifndef HILBERT_HOTEL_H
     #define HILBERT_HOTEL_H
@@ -93,6 +94,7 @@ an initialization state and a cleanup procedure.
     #endif
 
 .. code-block:: cpp
+    :caption: hilbert_hotel.cpp
 
     #include "hilbert_hotel.h"
 
@@ -235,8 +237,7 @@ an initialization state and a cleanup procedure.
     }
 
 .. code-block:: cpp
-
-    /* prime_225.h */
+    :caption: prime_255.h
 
     const uint64_t PRIME[225] = {
             2,3,5,7,11,13,17,19,23,
@@ -275,6 +276,7 @@ RID_Owner maintains a list of RIDs. In practice, RIDs are similar to writing
 object-oriented C code.
 
 .. code-block:: cpp
+    :caption: infinite_bus.h
 
     class InfiniteBus : public RID_Data {
         RID self;
@@ -329,8 +331,14 @@ In ``register_server_types()``, ``Engine::get_singleton()->add_singleton``
 is used to register the dummy class in GDScript.
 
 .. code-block:: cpp
+    :caption: register_types.h
 
-    /* register_types.cpp */
+    /* Yes, the word in the middle must be the same as the module folder name */
+    void register_hilbert_hotel_types();
+    void unregister_hilbert_hotel_types();
+
+.. code-block:: cpp
+    :caption: register_types.cpp
 
     #include "register_types.h"
 
@@ -361,14 +369,6 @@ is used to register the dummy class in GDScript.
         }
     }
 
-.. code-block:: cpp
-
-    /* register_types.h */
-
-    /* Yes, the word in the middle must be the same as the module folder name */
-    void register_hilbert_hotel_types();
-    void unregister_hilbert_hotel_types();
-
 - `servers/register_server_types.cpp <https://github.com/godotengine/godot/blob/master/servers/register_server_types.cpp>`__
 
 Bind methods

contributing/development/core_and_modules/custom_modules_in_cpp.rst

@@ -45,8 +45,7 @@ The example module will be called "summator" (``godot/modules/summator``).
 Inside we will create a summator class:
 
 .. code-block:: cpp
-
-    /* summator.h */
+    :caption: godot/modules/summator/summator.h
 
     #ifndef SUMMATOR_H
     #define SUMMATOR_H
@@ -74,8 +73,7 @@ Inside we will create a summator class:
 And then the cpp file.
 
 .. code-block:: cpp
-
-    /* summator.cpp */
+    :caption: godot/modules/summator/summator.cpp
 
     #include "summator.h"
 
@@ -116,8 +114,7 @@ need to be created:
 These files should contain the following:
 
 .. code-block:: cpp
-
-    /* register_types.h */
+    :caption: godot/modules/summator/register_types.h
 
     #include "modules/register_module_types.h"
 
@@ -126,8 +123,7 @@ These files should contain the following:
     /* yes, the word in the middle must be the same as the module folder name */
 
 .. code-block:: cpp
-
-    /* register_types.cpp */
+    :caption: godot/modules/summator/register_types.cpp
 
     #include "register_types.h"
 
@@ -152,6 +148,7 @@ Next, we need to create an ``SCsub`` file so the build system compiles
 this module:
 
 .. code-block:: python
+    :caption: godot/modules/summator/SCsub
 
     # SCsub
 
@@ -184,8 +181,7 @@ If you want to add custom compiler flags when building your module, you need to
 Example ``SCsub`` with custom flags:
 
 .. code-block:: python
-
-    # SCsub
+    :caption: godot/modules/summator/SCsub
 
     Import('env')
 
@@ -201,6 +197,7 @@ And finally, the configuration file for the module, this is a
 Python script that must be named ``config.py``:
 
 .. code-block:: python
+    :caption: godot/modules/summator/config.py
 
     # config.py
 
@@ -354,8 +351,7 @@ method which will be called before anything else during the
 We now need to add this method to ``register_types`` header and source files:
 
 .. code-block:: cpp
-
-    /* register_types.h */
+    :caption: godot/modules/summator/register_types.h
 
     #define MODULE_SUMMATOR_HAS_PREREGISTER
     void preregister_summator_types();
@@ -369,8 +365,7 @@ We now need to add this method to ``register_types`` header and source files:
           has to be converted to uppercase as well.
 
 .. code-block:: cpp
-
-    /* register_types.cpp */
+    :caption: godot/modules/summator/register_types.cpp
 
     #include "register_types.h"
 
@@ -413,8 +408,7 @@ The solution to avoid such a cost is to build our own module as a shared
 library that will be dynamically loaded when starting our game's binary.
 
 .. code-block:: python
-
-    # SCsub
+    :caption: godot/modules/summator/SCsub
 
     Import('env')
 
@@ -470,8 +464,7 @@ module as shared library (for development) or as a part of the Godot binary
 using the ``ARGUMENT`` command:
 
 .. code-block:: python
-
-    # SCsub
+    :caption: godot/modules/summator/SCsub
 
     Import('env')
 
@@ -626,8 +619,8 @@ The procedure is the following:
 3. Write some test cases. Here's an example:
 
 .. code-block:: cpp
+    :caption: godot/modules/summator/tests/test_summator.h
 
-    // test_summator.h
     #ifndef TEST_SUMMATOR_H
     #define TEST_SUMMATOR_H
 

contributing/development/core_and_modules/custom_resource_format_loaders.rst

@@ -56,8 +56,7 @@ read and handle data serialization.
 
 
 .. code-block:: cpp
-
-    /* resource_loader_json.h */
+    :caption: resource_loader_json.h
 
     #ifndef RESOURCE_LOADER_JSON_H
     #define RESOURCE_LOADER_JSON_H
@@ -75,8 +74,7 @@ read and handle data serialization.
     #endif // RESOURCE_LOADER_JSON_H
 
 .. code-block:: cpp
-
-    /* resource_loader_json.cpp */
+    :caption: resource_loader_json.cpp
 
     #include "resource_loader_json.h"
 
@@ -112,8 +110,7 @@ If you'd like to be able to edit and save a resource, you can implement a
 ``ResourceFormatSaver``:
 
 .. code-block:: cpp
-
-    /* resource_saver_json.h */
+    :caption: resource_saver_json.h
 
     #ifndef RESOURCE_SAVER_JSON_H
     #define RESOURCE_SAVER_JSON_H
@@ -130,8 +127,7 @@ If you'd like to be able to edit and save a resource, you can implement a
     #endif // RESOURCE_SAVER_JSON_H
 
 .. code-block:: cpp
-
-    /* resource_saver_json.cpp */
+    :caption: resource_saver_json.cpp
 
     #include "resource_saver_json.h"
 
@@ -164,8 +160,7 @@ understand additional binary formats such as machine learning models.
 Here is an example of creating a custom datatype:
 
 .. code-block:: cpp
-
-    /* resource_json.h */
+    :caption: resource_json.h
 
     #ifndef RESOURCE_JSON_H
     #define RESOURCE_JSON_H
@@ -197,8 +192,7 @@ Here is an example of creating a custom datatype:
     #endif // RESOURCE_JSON_H
 
 .. code-block:: cpp
-
-    /* resource_json.cpp */
+    :caption: resource_json.cpp
 
     #include "resource_json.h"
 
@@ -314,15 +308,13 @@ handler. The handler selects the proper loader automatically
 when ``load`` is called.
 
 .. code-block:: cpp
-
-    /* register_types.h */
+    :caption: register_types.h
 
     void register_json_types();
     void unregister_json_types();
 
 .. code-block:: cpp
-
-    /* register_types.cpp */
+    :caption: register_types.cpp
 
     #include "register_types.h"