/**************************************************************************/ /* editor_help.cpp */ /**************************************************************************/ /* This file is part of: */ /* GODOT ENGINE */ /* https://godotengine.org */ /**************************************************************************/ /* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */ /* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */ /* */ /* Permission is hereby granted, free of charge, to any person obtaining */ /* a copy of this software and associated documentation files (the */ /* "Software"), to deal in the Software without restriction, including */ /* without limitation the rights to use, copy, modify, merge, publish, */ /* distribute, sublicense, and/or sell copies of the Software, and to */ /* permit persons to whom the Software is furnished to do so, subject to */ /* the following conditions: */ /* */ /* The above copyright notice and this permission notice shall be */ /* included in all copies or substantial portions of the Software. */ /* */ /* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */ /* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */ /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */ /* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */ /* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */ /* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ /**************************************************************************/ #include "editor_help.h" #include "core/config/project_settings.h" #include "core/core_constants.h" #include "core/extension/gdextension.h" #include "core/input/input.h" #include "core/io/json.h" #include "core/object/script_language.h" #include "core/os/keyboard.h" #include "core/string/string_builder.h" #include "core/version_generated.gen.h" #include "editor/doc_data_compressed.gen.h" #include "editor/editor_main_screen.h" #include "editor/editor_node.h" #include "editor/editor_paths.h" #include "editor/editor_property_name_processor.h" #include "editor/editor_settings.h" #include "editor/editor_string_names.h" #include "editor/plugins/script_editor_plugin.h" #include "editor/themes/editor_scale.h" #include "scene/gui/line_edit.h" #include "modules/modules_enabled.gen.h" // For gdscript, mono. // For syntax highlighting. #ifdef MODULE_GDSCRIPT_ENABLED #include "modules/gdscript/editor/gdscript_highlighter.h" #include "modules/gdscript/gdscript.h" #endif // For syntax highlighting. #ifdef MODULE_MONO_ENABLED #include "editor/plugins/script_editor_plugin.h" #include "modules/mono/csharp_script.h" #endif #define CONTRIBUTE_URL vformat("%s/contributing/documentation/updating_the_class_reference.html", VERSION_DOCS_URL) #ifdef MODULE_MONO_ENABLED // Sync with the types mentioned in https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/c_sharp_differences.html const Vector classes_with_csharp_differences = { "@GlobalScope", "String", "NodePath", "Signal", "Callable", "RID", "Basis", "Transform2D", "Transform3D", "Rect2", "Rect2i", "AABB", "Quaternion", "Projection", "Color", "Array", "Dictionary", "PackedByteArray", "PackedColorArray", "PackedFloat32Array", "PackedFloat64Array", "PackedInt32Array", "PackedInt64Array", "PackedStringArray", "PackedVector2Array", "PackedVector3Array", "PackedVector4Array", "Variant", }; #endif static const String nbsp = String::chr(160); static const String nbsp_equal_nbsp = nbsp + "=" + nbsp; static const String colon_nbsp = ":" + nbsp; const Vector packed_array_types = { "PackedByteArray", "PackedColorArray", "PackedFloat32Array", "PackedFloat64Array", "PackedInt32Array", "PackedInt64Array", "PackedStringArray", "PackedVector2Array", "PackedVector3Array", "PackedVector4Array", }; static String _replace_nbsp_with_space(const String &p_string) { return p_string.replace(nbsp, " "); } static String _fix_constant(const String &p_constant) { if (p_constant.strip_edges() == "4294967295") { return "0xFFFFFFFF"; } if (p_constant.strip_edges() == "2147483647") { return "0x7FFFFFFF"; } if (p_constant.strip_edges() == "1048575") { return "0xFFFFF"; } return p_constant; } static void _add_qualifiers_to_rt(const String &p_qualifiers, RichTextLabel *p_rt) { for (const String &qualifier : p_qualifiers.split_spaces()) { String hint; if (qualifier == "vararg") { hint = TTR("This method supports a variable number of arguments."); } else if (qualifier == "virtual") { hint = TTR("This method is called by the engine.\nIt can be overridden to customize built-in behavior."); } else if (qualifier == "const") { hint = TTR("This method has no side effects.\nIt does not modify the object in any way."); } else if (qualifier == "static") { hint = TTR("This method does not need an instance to be called.\nIt can be called directly using the class name."); } p_rt->add_text(" "); if (hint.is_empty()) { p_rt->add_text(qualifier); } else { p_rt->push_hint(hint); p_rt->add_text(qualifier); p_rt->pop(); // hint } } } // Removes unnecessary prefix from `p_class_specifier` when within the `p_edited_class` context. static String _contextualize_class_specifier(const String &p_class_specifier, const String &p_edited_class) { // If this is a completely different context than the current class, then keep full path. if (!p_class_specifier.begins_with(p_edited_class)) { return p_class_specifier; } // Here equal `length()` and `begins_with()` from above implies `p_class_specifier == p_edited_class`. if (p_class_specifier.length() == p_edited_class.length()) { int rfind = p_class_specifier.rfind_char('.'); if (rfind == -1) { // Single identifier. return p_class_specifier; } // Multiple specifiers: keep last one only. return p_class_specifier.substr(rfind + 1); } // They share a _name_ prefix but not a _class specifier_ prefix, e.g. `Tree` and `TreeItem`. // `begins_with()` and `length()`s being different implies `p_class_specifier.length() > p_edited_class.length()` so this is safe. if (p_class_specifier[p_edited_class.length()] != '.') { return p_class_specifier; } // Remove class specifier prefix. return p_class_specifier.substr(p_edited_class.length() + 1); } /// EditorHelp /// // TODO: This is sometimes used directly as `doc->something`, other times as `EditorHelp::get_doc_data()`, which is thread-safe. // Might this be a problem? DocTools *EditorHelp::doc = nullptr; DocTools *EditorHelp::ext_doc = nullptr; int EditorHelp::doc_generation_count = 0; String EditorHelp::doc_version_hash; Thread EditorHelp::worker_thread; static bool _attempt_doc_load(const String &p_class) { // Docgen always happens in the outer-most class: it also generates docs for inner classes. const String outer_class = p_class.get_slicec('.', 0); if (!ScriptServer::is_global_class(outer_class)) { return false; } // `ResourceLoader` is used in order to have a script-agnostic way to load scripts. // This forces GDScript to compile the code, which is unnecessary for docgen, but it's a good compromise right now. const Ref