Doxygenify

.gitignore

@@ -81,7 +81,8 @@ __pycache__/
 .*_cache/
 
 # Documentation
-doc/_build/
+doc/_doxygen_output/
+doc/_doxygen_issues.txt
 
 # Android
 .gradle/

core/config/engine.cpp

@@ -30,6 +30,12 @@
 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
 /**************************************************************************/
 
+/**
+ * @file engine.cpp
+ *
+ * [Add any documentation that applies to the entire file here!]
+ */
+
 #include "engine.h"
 
 #include "core/authors.gen.h"

core/config/engine.h

@@ -32,6 +32,12 @@
 
 #pragma once
 
+/**
+ * @file engine.h
+ *
+ * [Add any documentation that applies to the entire file here!]
+ */
+
 #include "core/os/main_loop.h"
 #include "core/string/ustring.h"
 #include "core/templates/list.h"
@@ -44,7 +50,7 @@ class Engine {
 	struct Singleton {
 		StringName name;
 		Object *ptr = nullptr;
-		StringName class_name; // Used for binding generation hinting.
+		StringName class_name; ///< Used for binding generation hinting.
 		// Singleton scope flags.
 		bool user_created = false;
 		bool editor_only = false;

core/config/project_settings.cpp

@@ -30,6 +30,12 @@
 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
 /**************************************************************************/
 
+/**
+ * @file project_settings.cpp
+ *
+ * [Add any documentation that applies to the entire file here!]
+ */
+
 #include "project_settings.h"
 
 #include "core/core_bind.h" // For Compression enum.
@@ -71,8 +77,7 @@ String ProjectSettings::get_imported_files_path() const {
 }
 
 #ifdef TOOLS_ENABLED
-// Returns the features that a project must have when opened with this build of Redot.
-// This is used by the project manager to provide the initial_settings for config/features.
+
 const PackedStringArray ProjectSettings::get_required_features() {
 	PackedStringArray features;
 	features.append(REDOT_VERSION_BRANCH);
@@ -83,7 +88,6 @@ const PackedStringArray ProjectSettings::get_required_features() {
 	return features;
 }
 
-// Returns the features supported by this build of Redot. Includes all required features.
 const PackedStringArray ProjectSettings::_get_supported_features() {
 	PackedStringArray features = get_required_features();
 #ifdef MODULE_MONO_ENABLED
@@ -106,7 +110,6 @@ const PackedStringArray ProjectSettings::_get_supported_features() {
 	return features;
 }
 
-// Returns the features that this project needs but this build of Redot lacks.
 const PackedStringArray ProjectSettings::get_unsupported_features(const PackedStringArray &p_project_features) {
 	PackedStringArray unsupported_features;
 	PackedStringArray supported_features = singleton->_get_supported_features();
@@ -123,7 +126,6 @@ const PackedStringArray ProjectSettings::get_unsupported_features(const PackedSt
 	return unsupported_features;
 }
 
-// Returns the features that both this project has and this build of Redot has, ensuring required features exist.
 const PackedStringArray ProjectSettings::_trim_to_supported_features(const PackedStringArray &p_project_features) {
 	// Remove unsupported features if present.
 	PackedStringArray features = PackedStringArray(p_project_features);
@@ -602,33 +604,6 @@ void ProjectSettings::_convert_to_last_version(int p_from_version) {
 #endif // DISABLE_DEPRECATED
 }
 
-/*
- * This method is responsible for loading a project.godot file and/or data file
- * using the following merit order:
- *  - If using NetworkClient, try to lookup project file or fail.
- *  - If --main-pack was passed by the user (`p_main_pack`), load it or fail.
- *  - Search for project PCKs automatically. For each step we try loading a potential
- *    PCK, and if it doesn't work, we proceed to the next step. If any step succeeds,
- *    we try loading the project settings, and abort if it fails. Steps:
- *    o Bundled PCK in the executable.
- *    o [macOS only] PCK with same basename as the binary in the .app resource dir.
- *    o PCK with same basename as the binary in the binary's directory. We handle both
- *      changing the extension to '.pck' (e.g. 'win_game.exe' -> 'win_game.pck') and
- *      appending '.pck' to the binary name (e.g. 'linux_game' -> 'linux_game.pck').
- *    o PCK with the same basename as the binary in the current working directory.
- *      Same as above for the two possible PCK file names.
- *  - On Android, look for 'assets.sparsepck' and try loading it, if it doesn't work,
- *    proceed to the next step.
- *  - On relevant platforms (Android/iOS), lookup project file in OS resource path.
- *    If found, load it or fail.
- *  - Lookup project file in passed `p_path` (--path passed by the user), i.e. we
- *    are running from source code.
- *    If not found and `p_upwards` is true (--upwards passed by the user), look for
- *    project files in parent folders up to the system root (used to run a game
- *    from command line while in a subfolder).
- *    If a project file is found, load it or fail.
- *    If nothing was found, error out.
- */
 Error ProjectSettings::_setup(const String &p_path, const String &p_main_pack, bool p_upwards, bool p_ignore_override) {
 	if (!OS::get_singleton()->get_resource_dir().is_empty()) {
 		// OS will call ProjectSettings->get_resource_path which will be empty if not overridden!
@@ -864,8 +839,8 @@ Error ProjectSettings::_load_settings_text(const String &p_path) {
 	Ref<FileAccess> f = FileAccess::open(p_path, FileAccess::READ, &err);
 
 	if (f.is_null()) {
-		// FIXME: Above 'err' error code is ERR_FILE_CANT_OPEN if the file is missing
-		// This needs to be streamlined if we want decent error reporting
+		/// @todo FIXME: Above 'err' error code is ERR_FILE_CANT_OPEN if the file is missing
+		/// This needs to be streamlined if we want decent error reporting
 		return ERR_FILE_NOT_FOUND;
 	}
 
@@ -1317,7 +1292,6 @@ Variant ProjectSettings::get_setting(const String &p_setting, const Variant &p_d
 }
 
 void ProjectSettings::refresh_global_class_list() {
-	// This is called after mounting a new PCK file to pick up class changes.
 	is_global_class_list_loaded = false; // Make sure we read from the freshly mounted PCK.
 	Array script_classes = get_global_class_list();
 	for (int i = 0; i < script_classes.size(); i++) {
@@ -1539,9 +1513,6 @@ void ProjectSettings::_add_builtin_input_map() {
 }
 
 ProjectSettings::ProjectSettings() {
-	// Initialization of engine variables should be done in the setup() method,
-	// so that the values can be overridden from project.redot or project.binary.
-
 	CRASH_COND_MSG(singleton != nullptr, "Instantiating a new ProjectSettings singleton is not supported.");
 	singleton = this;
 

core/config/project_settings.h

@@ -32,6 +32,12 @@
 
 #pragma once
 
+/**
+ * @file project_settings.h
+ *
+ * [Add any documentation that applies to the entire file here!]
+ */
+
 #include "core/object/class_db.h"
 
 template <typename T>
@@ -44,20 +50,23 @@ class ProjectSettings : public Object {
 
 	bool is_changed = false;
 
-	// Starting version from 1 ensures that all callers can reset their tested version to 0,
-	// and will always detect the initial project settings as a "change".
+	/// Starting version from 1 ensures that all callers can reset their tested version to 0,
+	/// and will always detect the initial project settings as a "change".
 	uint32_t _version = 1;
 
 public:
 	typedef HashMap<String, Variant> CustomMap;
 	static inline const String PROJECT_DATA_DIR_NAME_SUFFIX = "godot";
 	static inline const String EDITOR_SETTING_OVERRIDE_PREFIX = "editor_overrides/";
 
-	// Properties that are not for built in values begin from this value, so builtin ones are displayed first.
+	/// Properties that are not for built in values begin from this value, so builtin ones are displayed first.
 	constexpr static const int32_t NO_BUILTIN_ORDER_BASE = 1 << 16;
 
 #ifdef TOOLS_ENABLED
+	/// Returns the features that a project must have when opened with this build of Redot.
+	/// This is used by the project manager to provide the initial_settings for config/features.
 	const static PackedStringArray get_required_features();
+	/// Returns the features that this project needs but this build of Redot lacks.
 	const static PackedStringArray get_unsupported_features(const PackedStringArray &p_project_features);
 #endif // TOOLS_ENABLED
 
@@ -94,7 +103,7 @@ class ProjectSettings : public Object {
 	int last_builtin_order = 0;
 	uint64_t last_save_time = 0;
 
-	RBMap<StringName, VariantContainer> props; // NOTE: Key order is used e.g. in the save_custom method.
+	RBMap<StringName, VariantContainer> props; ///< @note Key order is used e.g. in the save_custom method.
 	String resource_path;
 	HashMap<StringName, PropertyInfo> custom_prop_info;
 	bool using_datapack = false;
@@ -135,7 +144,9 @@ class ProjectSettings : public Object {
 	Error _save_custom_bnd(const String &p_file);
 
 #ifdef TOOLS_ENABLED
+	/// @return The features supported by this build of Redot. Includes all required features.
 	const static PackedStringArray _get_supported_features();
+	/// @return The features that both this project has and this build of Redot has, ensuring required features exist.
 	const static PackedStringArray _trim_to_supported_features(const PackedStringArray &p_project_features);
 #endif // TOOLS_ENABLED
 
@@ -146,6 +157,33 @@ class ProjectSettings : public Object {
 
 	void _add_property_info_bind(const Dictionary &p_info);
 
+	/**
+	 * This method is responsible for loading a project.godot file and/or data file
+	 * using the following merit order:
+	 *  - If using NetworkClient, try to lookup project file or fail.
+	 *  - If --main-pack was passed by the user (`p_main_pack`), load it or fail.
+	 *  - Search for project PCKs automatically. For each step we try loading a potential
+	 *    PCK, and if it doesn't work, we proceed to the next step. If any step succeeds,
+	 *    we try loading the project settings, and abort if it fails. Steps:
+	 *    o Bundled PCK in the executable.
+	 *    o [macOS only] PCK with same basename as the binary in the .app resource dir.
+	 *    o PCK with same basename as the binary in the binary's directory. We handle both
+	 *      changing the extension to '.pck' (e.g. 'win_game.exe' -> 'win_game.pck') and
+	 *      appending '.pck' to the binary name (e.g. 'linux_game' -> 'linux_game.pck').
+	 *    o PCK with the same basename as the binary in the current working directory.
+	 *      Same as above for the two possible PCK file names.
+	 *  - On Android, look for 'assets.sparsepck' and try loading it, if it doesn't work,
+	 *    proceed to the next step.
+	 *  - On relevant platforms (Android/iOS), lookup project file in OS resource path.
+	 *    If found, load it or fail.
+	 *  - Lookup project file in passed `p_path` (--path passed by the user), i.e. we
+	 *    are running from source code.
+	 *    If not found and `p_upwards` is true (--upwards passed by the user), look for
+	 *    project files in parent folders up to the system root (used to run a game
+	 *    from command line while in a subfolder).
+	 *    If a project file is found, load it or fail.
+	 *    If nothing was found, error out.
+	 */
 	Error _setup(const String &p_path, const String &p_main_pack, bool p_upwards = false, bool p_ignore_override = false);
 
 	void _add_builtin_input_map();
@@ -163,7 +201,7 @@ class ProjectSettings : public Object {
 	void set_setting(const String &p_setting, const Variant &p_value);
 	Variant get_setting(const String &p_setting, const Variant &p_default_value = Variant()) const;
 	TypedArray<Dictionary> get_global_class_list();
-	void refresh_global_class_list();
+	void refresh_global_class_list(); ///< This is called after mounting a new PCK file to pick up class changes.
 	void store_global_class_list(const Array &p_classes);
 	String get_global_class_list_path() const;
 
@@ -229,7 +267,7 @@ class ProjectSettings : public Object {
 	String get_scene_groups_cache_path() const;
 	void load_scene_groups_cache();
 
-	// Testing a version allows fast cached GET_GLOBAL macros.
+	/// Testing a version allows fast cached GET_GLOBAL macros.
 	uint32_t get_version() const { return _version; }
 
 #ifdef TOOLS_ENABLED
@@ -240,6 +278,8 @@ class ProjectSettings : public Object {
 	bool has_editor_setting_override(const String &p_setting) const;
 	Variant get_editor_setting_override(const String &p_setting) const;
 
+	/// Initialization of engine variables should be done in the setup() method,
+	/// so that the values can be overridden from project.redot or project.binary.
 	ProjectSettings();
 	ProjectSettings(const String &p_path);
 	~ProjectSettings();
@@ -263,9 +303,9 @@ Variant _GLOBAL_DEF(const PropertyInfo &p_info, const Variant &p_default, bool p
 #define GLOBAL_DEF_INTERNAL(m_var, m_value) _GLOBAL_DEF(m_var, m_value, false, false, false, true)
 
 /////////////////////////////////////////////////////////////////////////////////////////
-// Cached versions of GLOBAL_GET.
-// Cached but uses a typed variable for storage, this can be more efficient.
-// Variables prefixed with _ggc_ to avoid shadowing warnings.
+/// Cached versions of GLOBAL_GET.
+/// Cached but uses a typed variable for storage, this can be more efficient.
+/// Variables prefixed with _ggc_ to avoid shadowing warnings.
 #define GLOBAL_GET_CACHED(m_type, m_setting_name) ([](const char *p_name) -> m_type {\
 static_assert(std::is_trivially_destructible<m_type>::value, "GLOBAL_GET_CACHED must use a trivial type that allows static lifetime.");\
 static m_type _ggc_local_var;\

core/core_bind.cpp

@@ -30,6 +30,12 @@
 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
 /**************************************************************************/
 
+/**
+ * @file core_bind.cpp
+ *
+ * [Add any documentation that applies to the entire file here!]
+ */
+
 #include "core_bind.h"
 #include "core_bind.compat.inc"
 
@@ -598,15 +604,13 @@ Dictionary OS::get_memory_info() const {
 	return ::OS::get_singleton()->get_memory_info();
 }
 
-/** This method uses a signed argument for better error reporting as it's used from the scripting API. */
 void OS::delay_usec(int p_usec) const {
 	ERR_FAIL_COND_MSG(
 			p_usec < 0,
 			vformat("Can't sleep for %d microseconds. The delay provided must be greater than or equal to 0 microseconds.", p_usec));
 	::OS::get_singleton()->delay_usec(p_usec);
 }
 
-/** This method uses a signed argument for better error reporting as it's used from the scripting API. */
 void OS::delay_msec(int p_msec) const {
 	ERR_FAIL_COND_MSG(
 			p_msec < 0,
@@ -639,22 +643,18 @@ String OS::get_user_data_dir() const {
 }
 
 String OS::get_config_dir() const {
-	// Exposed as `get_config_dir()` instead of `get_config_path()` for consistency with other exposed OS methods.
 	return ::OS::get_singleton()->get_config_path();
 }
 
 String OS::get_data_dir() const {
-	// Exposed as `get_data_dir()` instead of `get_data_path()` for consistency with other exposed OS methods.
 	return ::OS::get_singleton()->get_data_path();
 }
 
 String OS::get_cache_dir() const {
-	// Exposed as `get_cache_dir()` instead of `get_cache_path()` for consistency with other exposed OS methods.
 	return ::OS::get_singleton()->get_cache_path();
 }
 
 String OS::get_temp_dir() const {
-	// Exposed as `get_temp_dir()` instead of `get_temp_path()` for consistency with other exposed OS methods.
 	return ::OS::get_singleton()->get_temp_path();
 }