From d0e7d9b62f0bcc2ba438b12c8bfbf68d82fff0ea Mon Sep 17 00:00:00 2001 From: Thakee Nathees Date: Sun, 29 Nov 2020 08:07:57 +0530 Subject: Documentation generation for GDScript - ClassDoc added to GDScript and property reflection data were extracted from parse tree - GDScript comments are collected from tokenizer for documentation and applied to the ClassDoc by the GDScript compiler - private docs were excluded (name with underscore prefix and doesn't have any doc comments) - default values (of non exported vars), arguments are extraced from the parser - Integrated with GDScript 2.0 and new enums were added. - merge conflicts fixed --- editor/doc_data.cpp | 71 ++++++++++- editor/doc_data.h | 29 +++++ editor/editor_file_system.cpp | 9 ++ editor/editor_help.cpp | 210 ++++++++++++++++++++++++-------- editor/editor_help.h | 1 + editor/plugins/script_editor_plugin.cpp | 12 ++ editor/plugins/script_editor_plugin.h | 1 + 7 files changed, 279 insertions(+), 54 deletions(-) (limited to 'editor') diff --git a/editor/doc_data.cpp b/editor/doc_data.cpp index 165a5c8546..d786806ffa 100644 --- a/editor/doc_data.cpp +++ b/editor/doc_data.cpp @@ -185,7 +185,24 @@ void DocData::remove_from(const DocData &p_data) { } } -static void return_doc_from_retinfo(DocData::MethodDoc &p_method, const PropertyInfo &p_retinfo) { +void DocData::add_doc(const ClassDoc &p_class_doc) { + ERR_FAIL_COND(p_class_doc.name == ""); + class_list[p_class_doc.name] = p_class_doc; +} + +void DocData::remove_doc(const String &p_class_name) { + ERR_FAIL_COND(p_class_name == "" || !class_list.has(p_class_name)); + class_list.erase(p_class_name); +} + +bool DocData::has_doc(const String &p_class_name) { + if (p_class_name == "") { + return false; + } + return class_list.has(p_class_name); +} + +void DocData::return_doc_from_retinfo(DocData::MethodDoc &p_method, const PropertyInfo &p_retinfo) { if (p_retinfo.type == Variant::INT && p_retinfo.usage & PROPERTY_USAGE_CLASS_IS_ENUM) { p_method.return_enum = p_retinfo.class_name; if (p_method.return_enum.begins_with("_")) { //proxy class @@ -207,7 +224,7 @@ static void return_doc_from_retinfo(DocData::MethodDoc &p_method, const Property } } -static void argument_doc_from_arginfo(DocData::ArgumentDoc &p_argument, const PropertyInfo &p_arginfo) { +void DocData::argument_doc_from_arginfo(DocData::ArgumentDoc &p_argument, const PropertyInfo &p_arginfo) { p_argument.name = p_arginfo.name; if (p_arginfo.type == Variant::INT && p_arginfo.usage & PROPERTY_USAGE_CLASS_IS_ENUM) { @@ -230,6 +247,56 @@ static void argument_doc_from_arginfo(DocData::ArgumentDoc &p_argument, const Pr } } +void DocData::property_doc_from_scriptmemberinfo(DocData::PropertyDoc &p_property, const ScriptMemberInfo &p_memberinfo) { + p_property.name = p_memberinfo.propinfo.name; + p_property.description = p_memberinfo.doc_string; + + if (p_memberinfo.propinfo.type == Variant::OBJECT) { + p_property.type = p_memberinfo.propinfo.class_name; + } else if (p_memberinfo.propinfo.type == Variant::NIL && p_memberinfo.propinfo.usage & PROPERTY_USAGE_NIL_IS_VARIANT) { + p_property.type = "Variant"; + } else { + p_property.type = Variant::get_type_name(p_memberinfo.propinfo.type); + } + + p_property.setter = p_memberinfo.setter; + p_property.getter = p_memberinfo.getter; + + if (p_memberinfo.has_default_value && p_memberinfo.default_value.get_type() != Variant::OBJECT) { + p_property.default_value = p_memberinfo.default_value.get_construct_string().replace("\n", ""); + } + + p_property.overridden = false; +} + +void DocData::method_doc_from_methodinfo(DocData::MethodDoc &p_method, const MethodInfo &p_methodinfo, const String &p_desc) { + p_method.name = p_methodinfo.name; + p_method.description = p_desc; + + return_doc_from_retinfo(p_method, p_methodinfo.return_val); + + for (int i = 0; i < p_methodinfo.arguments.size(); i++) { + ArgumentDoc argument; + argument_doc_from_arginfo(argument, p_methodinfo.arguments[i]); + int default_arg_index = i - (p_methodinfo.arguments.size() - p_methodinfo.default_arguments.size()); + if (default_arg_index >= 0) { + Variant default_arg = p_methodinfo.default_arguments[default_arg_index]; + argument.default_value = default_arg.get_construct_string(); + } + p_method.arguments.push_back(argument); + } +} + +void DocData::constant_doc_from_variant(DocData::ConstantDoc &p_const, const StringName &p_name, const Variant &p_value, const String &p_desc) { + p_const.name = p_name; + p_const.value = p_value; + p_const.description = p_desc; +} + +void DocData::signal_doc_from_methodinfo(DocData::MethodDoc &p_signal, const MethodInfo &p_methodinfo, const String &p_desc) { + return method_doc_from_methodinfo(p_signal, p_methodinfo, p_desc); +} + static Variant get_documentation_default_value(const StringName &p_class_name, const StringName &p_property_name, bool &r_default_value_valid) { Variant default_value = Variant(); r_default_value_valid = false; diff --git a/editor/doc_data.h b/editor/doc_data.h index 2cb475d137..0090a97c93 100644 --- a/editor/doc_data.h +++ b/editor/doc_data.h @@ -35,6 +35,16 @@ #include "core/templates/map.h" #include "core/variant/variant.h" +struct ScriptMemberInfo { + PropertyInfo propinfo; + String doc_string; + StringName setter; + StringName getter; + + bool has_default_value = false; + Variant default_value; +}; + class DocData { public: struct ArgumentDoc { @@ -87,6 +97,12 @@ public: } }; + struct EnumDoc { + String name = "@unnamed_enum"; + String description; + Vector values; + }; + struct PropertyDoc { String name; String type; @@ -115,8 +131,11 @@ public: Vector methods; Vector signals; Vector constants; + Map enums; Vector properties; Vector theme_properties; + bool is_script_doc = false; + String script_path; bool operator<(const ClassDoc &p_class) const { return name < p_class.name; } @@ -128,8 +147,18 @@ public: Error _load(Ref parser); public: + static void return_doc_from_retinfo(DocData::MethodDoc &p_method, const PropertyInfo &p_retinfo); + static void argument_doc_from_arginfo(DocData::ArgumentDoc &p_argument, const PropertyInfo &p_arginfo); + static void property_doc_from_scriptmemberinfo(DocData::PropertyDoc &p_property, const ScriptMemberInfo &p_memberinfo); + static void method_doc_from_methodinfo(DocData::MethodDoc &p_method, const MethodInfo &p_methodinfo, const String &p_desc); + static void constant_doc_from_variant(DocData::ConstantDoc &p_const, const StringName &p_name, const Variant &p_value, const String &p_desc); + static void signal_doc_from_methodinfo(DocData::MethodDoc &p_signal, const MethodInfo &p_methodinfo, const String &p_desc); + void merge_from(const DocData &p_data); void remove_from(const DocData &p_data); + void add_doc(const ClassDoc &p_class_doc); + void remove_doc(const String &p_class_name); + bool has_doc(const String &p_class_name); void generate(bool p_basic_types = false); Error load_classes(const String &p_dir); static Error erase_classes(const String &p_dir); diff --git a/editor/editor_file_system.cpp b/editor/editor_file_system.cpp index c66bc9b3fa..44c29ab81f 100644 --- a/editor/editor_file_system.cpp +++ b/editor/editor_file_system.cpp @@ -799,6 +799,15 @@ void EditorFileSystem::_scan_new_dir(EditorFileSystemDirectory *p_dir, DirAccess } } + if (fc) { + for (int i = 0; i < ScriptServer::get_language_count(); i++) { + ScriptLanguage *lang = ScriptServer::get_language(i); + if (lang->has_documentation() && fc->type == lang->get_type()) { + ResourceLoader::load(path); + } + } + } + p_dir->files.push_back(fi); p_progress.update(idx, total); } diff --git a/editor/editor_help.cpp b/editor/editor_help.cpp index 2c49782fd2..e9f6b16b88 100644 --- a/editor/editor_help.cpp +++ b/editor/editor_help.cpp @@ -388,7 +388,7 @@ void EditorHelp::_update_doc() { } // Descendents - if (ClassDB::class_exists(cd.name)) { + if (cd.is_script_doc || ClassDB::class_exists(cd.name)) { bool found = false; bool prev = false; @@ -494,7 +494,19 @@ void EditorHelp::_update_doc() { Set skip_methods; bool property_descr = false; - if (cd.properties.size()) { + bool has_properties = cd.properties.size() != 0; + if (cd.is_script_doc) { + has_properties = false; + for (int i = 0; i < cd.properties.size(); i++) { + if (cd.properties[i].name.begins_with("_") && cd.properties[i].description.empty()) { + continue; + } + has_properties = true; + break; + } + } + + if (has_properties) { section_line.push_back(Pair(TTR("Properties"), class_desc->get_line_count() - 2)); class_desc->push_color(title_color); class_desc->push_font(doc_title_font); @@ -509,6 +521,10 @@ void EditorHelp::_update_doc() { class_desc->set_table_column_expand(1, true); for (int i = 0; i < cd.properties.size(); i++) { + // Ignore undocumented private. + if (cd.properties[i].name.begins_with("_") && cd.properties[i].description.empty()) { + continue; + } property_line[cd.properties[i].name] = class_desc->get_line_count() - 2; //gets overridden if description class_desc->push_cell(); @@ -565,6 +581,32 @@ void EditorHelp::_update_doc() { class_desc->pop(); } + if (cd.is_script_doc && (cd.properties[i].setter != "" || cd.properties[i].getter != "")) { + class_desc->push_color(symbol_color); + class_desc->add_text(" [" + TTR("property:") + " "); + class_desc->pop(); // color + + if (cd.properties[i].setter != "") { + class_desc->push_color(value_color); + class_desc->add_text("setter"); + class_desc->pop(); // color + } + if (cd.properties[i].getter != "") { + if (cd.properties[i].setter != "") { + class_desc->push_color(symbol_color); + class_desc->add_text(", "); + class_desc->pop(); // color + } + class_desc->push_color(value_color); + class_desc->add_text("getter"); + class_desc->pop(); // color + } + + class_desc->push_color(symbol_color); + class_desc->add_text("]"); + class_desc->pop(); // color + } + class_desc->pop(); class_desc->pop(); @@ -590,6 +632,10 @@ void EditorHelp::_update_doc() { continue; } } + // Ignore undocumented private. + if (cd.methods[i].name.begins_with("_") && cd.methods[i].description.empty()) { + continue; + } methods.push_back(cd.methods[i]); } @@ -802,13 +848,17 @@ void EditorHelp::_update_doc() { Vector constants; for (int i = 0; i < cd.constants.size(); i++) { - if (cd.constants[i].enumeration != String()) { + if (!cd.constants[i].enumeration.empty()) { if (!enums.has(cd.constants[i].enumeration)) { enums[cd.constants[i].enumeration] = Vector(); } enums[cd.constants[i].enumeration].push_back(cd.constants[i]); } else { + // Ignore undocumented private. + if (cd.constants[i].name.begins_with("_") && cd.constants[i].description.empty()) { + continue; + } constants.push_back(cd.constants[i]); } } @@ -848,6 +898,19 @@ void EditorHelp::_update_doc() { class_desc->add_newline(); class_desc->add_newline(); + // Enum description. + if (e != "@unnamed_enums" && cd.enums.has(e)) { + class_desc->push_color(text_color); + class_desc->push_font(doc_font); + class_desc->push_indent(1); + _add_text(cd.enums[e]); + class_desc->pop(); + class_desc->pop(); + class_desc->pop(); + class_desc->add_newline(); + class_desc->add_newline(); + } + class_desc->push_indent(1); Vector enum_list = E->get(); @@ -1018,60 +1081,89 @@ void EditorHelp::_update_doc() { class_desc->pop(); // color } + if (cd.is_script_doc && (cd.properties[i].setter != "" || cd.properties[i].getter != "")) { + class_desc->push_color(symbol_color); + class_desc->add_text(" [" + TTR("property:") + " "); + class_desc->pop(); // color + + if (cd.properties[i].setter != "") { + class_desc->push_color(value_color); + class_desc->add_text("setter"); + class_desc->pop(); // color + } + if (cd.properties[i].getter != "") { + if (cd.properties[i].setter != "") { + class_desc->push_color(symbol_color); + class_desc->add_text(", "); + class_desc->pop(); // color + } + class_desc->push_color(value_color); + class_desc->add_text("getter"); + class_desc->pop(); // color + } + + class_desc->push_color(symbol_color); + class_desc->add_text("]"); + class_desc->pop(); // color + } + class_desc->pop(); // font class_desc->pop(); // cell - Map method_map; - for (int j = 0; j < methods.size(); j++) { - method_map[methods[j].name] = methods[j]; - } + // Script doc doesn't have setter, getter. + if (!cd.is_script_doc) { + Map method_map; + for (int j = 0; j < methods.size(); j++) { + method_map[methods[j].name] = methods[j]; + } - if (cd.properties[i].setter != "") { - class_desc->push_cell(); - class_desc->pop(); // cell + if (cd.properties[i].setter != "") { + class_desc->push_cell(); + class_desc->pop(); // cell - class_desc->push_cell(); - class_desc->push_font(doc_code_font); - class_desc->push_color(text_color); - if (method_map[cd.properties[i].setter].arguments.size() > 1) { - // Setters with additional arguments are exposed in the method list, so we link them here for quick access. - class_desc->push_meta("@method " + cd.properties[i].setter); - class_desc->add_text(cd.properties[i].setter + TTR("(value)")); - class_desc->pop(); - } else { - class_desc->add_text(cd.properties[i].setter + TTR("(value)")); + class_desc->push_cell(); + class_desc->push_font(doc_code_font); + class_desc->push_color(text_color); + if (method_map[cd.properties[i].setter].arguments.size() > 1) { + // Setters with additional arguments are exposed in the method list, so we link them here for quick access. + class_desc->push_meta("@method " + cd.properties[i].setter); + class_desc->add_text(cd.properties[i].setter + TTR("(value)")); + class_desc->pop(); + } else { + class_desc->add_text(cd.properties[i].setter + TTR("(value)")); + } + class_desc->pop(); // color + class_desc->push_color(comment_color); + class_desc->add_text(" setter"); + class_desc->pop(); // color + class_desc->pop(); // font + class_desc->pop(); // cell + method_line[cd.properties[i].setter] = property_line[cd.properties[i].name]; } - class_desc->pop(); // color - class_desc->push_color(comment_color); - class_desc->add_text(" setter"); - class_desc->pop(); // color - class_desc->pop(); // font - class_desc->pop(); // cell - method_line[cd.properties[i].setter] = property_line[cd.properties[i].name]; - } - if (cd.properties[i].getter != "") { - class_desc->push_cell(); - class_desc->pop(); // cell + if (cd.properties[i].getter != "") { + class_desc->push_cell(); + class_desc->pop(); // cell - class_desc->push_cell(); - class_desc->push_font(doc_code_font); - class_desc->push_color(text_color); - if (method_map[cd.properties[i].getter].arguments.size() > 0) { - // Getters with additional arguments are exposed in the method list, so we link them here for quick access. - class_desc->push_meta("@method " + cd.properties[i].getter); - class_desc->add_text(cd.properties[i].getter + "()"); - class_desc->pop(); - } else { - class_desc->add_text(cd.properties[i].getter + "()"); + class_desc->push_cell(); + class_desc->push_font(doc_code_font); + class_desc->push_color(text_color); + if (method_map[cd.properties[i].getter].arguments.size() > 0) { + // Getters with additional arguments are exposed in the method list, so we link them here for quick access. + class_desc->push_meta("@method " + cd.properties[i].getter); + class_desc->add_text(cd.properties[i].getter + "()"); + class_desc->pop(); + } else { + class_desc->add_text(cd.properties[i].getter + "()"); + } + class_desc->pop(); //color + class_desc->push_color(comment_color); + class_desc->add_text(" getter"); + class_desc->pop(); //color + class_desc->pop(); //font + class_desc->pop(); //cell + method_line[cd.properties[i].getter] = property_line[cd.properties[i].name]; } - class_desc->pop(); //color - class_desc->push_color(comment_color); - class_desc->add_text(" getter"); - class_desc->pop(); //color - class_desc->pop(); //font - class_desc->pop(); //cell - method_line[cd.properties[i].getter] = property_line[cd.properties[i].name]; } class_desc->pop(); // table @@ -1082,13 +1174,17 @@ void EditorHelp::_update_doc() { class_desc->push_color(text_color); class_desc->push_font(doc_font); class_desc->push_indent(1); - if (cd.properties[i].description.strip_edges() != String()) { + if (!cd.properties[i].description.strip_edges().empty()) { _add_text(DTR(cd.properties[i].description)); } else { class_desc->add_image(get_theme_icon("Error", "EditorIcons")); class_desc->add_text(" "); class_desc->push_color(comment_color); - class_desc->append_bbcode(TTR("There is currently no description for this property. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text)); + if (cd.is_script_doc) { + class_desc->append_bbcode(TTR("There is currently no description for this property.")); + } else { + class_desc->append_bbcode(TTR("There is currently no description for this property. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text)); + } class_desc->pop(); } class_desc->pop(); @@ -1133,13 +1229,17 @@ void EditorHelp::_update_doc() { class_desc->push_color(text_color); class_desc->push_font(doc_font); class_desc->push_indent(1); - if (methods_filtered[i].description.strip_edges() != String()) { + if (!methods_filtered[i].description.strip_edges().empty()) { _add_text(DTR(methods_filtered[i].description)); } else { class_desc->add_image(get_theme_icon("Error", "EditorIcons")); class_desc->add_text(" "); class_desc->push_color(comment_color); - class_desc->append_bbcode(TTR("There is currently no description for this method. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text)); + if (cd.is_script_doc) { + class_desc->append_bbcode(TTR("There is currently no description for this method.")); + } else { + class_desc->append_bbcode(TTR("There is currently no description for this method. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text)); + } class_desc->pop(); } @@ -1549,6 +1649,12 @@ void EditorHelp::go_to_class(const String &p_class, int p_scroll) { _goto_desc(p_class, p_scroll); } +void EditorHelp::update_doc() { + ERR_FAIL_COND(!doc->class_list.has(edited_class)); + ERR_FAIL_COND(!doc->class_list[edited_class].is_script_doc); + _update_doc(); +} + Vector> EditorHelp::get_sections() { Vector> sections; diff --git a/editor/editor_help.h b/editor/editor_help.h index cdb674cffd..545147f6f5 100644 --- a/editor/editor_help.h +++ b/editor/editor_help.h @@ -170,6 +170,7 @@ public: void go_to_help(const String &p_help); void go_to_class(const String &p_class, int p_scroll = 0); + void update_doc(); Vector> get_sections(); void scroll_to_section(int p_section_index); diff --git a/editor/plugins/script_editor_plugin.cpp b/editor/plugins/script_editor_plugin.cpp index 6ee8193291..fa70415210 100644 --- a/editor/plugins/script_editor_plugin.cpp +++ b/editor/plugins/script_editor_plugin.cpp @@ -2900,6 +2900,18 @@ void ScriptEditor::_help_class_goto(const String &p_desc) { _save_layout(); } +void ScriptEditor::update_doc(const String &p_name) { + ERR_FAIL_COND(!EditorHelp::get_doc_data()->has_doc(p_name)); + + for (int i = 0; i < tab_container->get_child_count(); i++) { + EditorHelp *eh = Object::cast_to(tab_container->get_child(i)); + if (eh && eh->get_class() == p_name) { + eh->update_doc(); + return; + } + } +} + void ScriptEditor::_update_selected_editor_menu() { for (int i = 0; i < tab_container->get_child_count(); i++) { bool current = tab_container->get_current_tab() == i; diff --git a/editor/plugins/script_editor_plugin.h b/editor/plugins/script_editor_plugin.h index f1453c3d20..cc02a1ccbe 100644 --- a/editor/plugins/script_editor_plugin.h +++ b/editor/plugins/script_editor_plugin.h @@ -482,6 +482,7 @@ public: void close_builtin_scripts_from_scene(const String &p_scene); void goto_help(const String &p_desc) { _help_class_goto(p_desc); } + void update_doc(const String &p_name); bool can_take_away_focus() const; -- cgit v1.2.3 From 42bfa169960b59c5d9337e9f63862f5feae92d58 Mon Sep 17 00:00:00 2001 From: Thakee Nathees Date: Sun, 29 Nov 2020 09:12:06 +0530 Subject: Refactor DocData into core and editor (DocTools) parts --- editor/connections_dialog.cpp | 3 +- editor/doc_data.cpp | 1431 ------------------------------- editor/doc_data.h | 170 ---- editor/doc_tools.cpp | 1336 +++++++++++++++++++++++++++++ editor/doc_tools.h | 56 ++ editor/editor_file_system.cpp | 15 +- editor/editor_help.cpp | 8 +- editor/editor_help.h | 6 +- editor/editor_inspector.cpp | 5 +- editor/plugins/script_editor_plugin.cpp | 64 ++ editor/property_selector.cpp | 3 +- 11 files changed, 1480 insertions(+), 1617 deletions(-) delete mode 100644 editor/doc_data.cpp delete mode 100644 editor/doc_data.h create mode 100644 editor/doc_tools.cpp create mode 100644 editor/doc_tools.h (limited to 'editor') diff --git a/editor/connections_dialog.cpp b/editor/connections_dialog.cpp index 320e5d8510..a8ff8a6854 100644 --- a/editor/connections_dialog.cpp +++ b/editor/connections_dialog.cpp @@ -31,6 +31,7 @@ #include "connections_dialog.h" #include "core/string/print_string.h" +#include "editor/doc_tools.h" #include "editor_node.h" #include "editor_scale.h" #include "editor_settings.h" @@ -997,7 +998,7 @@ void ConnectionsDock::update_tree() { } if (!found) { - DocData *dd = EditorHelp::get_doc_data(); + DocTools *dd = EditorHelp::get_doc_data(); Map::Element *F = dd->class_list.find(base); while (F && descr == String()) { for (int i = 0; i < F->get().signals.size(); i++) { diff --git a/editor/doc_data.cpp b/editor/doc_data.cpp deleted file mode 100644 index d786806ffa..0000000000 --- a/editor/doc_data.cpp +++ /dev/null @@ -1,1431 +0,0 @@ -/*************************************************************************/ -/* doc_data.cpp */ -/*************************************************************************/ -/* This file is part of: */ -/* GODOT ENGINE */ -/* https://godotengine.org */ -/*************************************************************************/ -/* Copyright (c) 2007-2020 Juan Linietsky, Ariel Manzur. */ -/* Copyright (c) 2014-2020 Godot Engine contributors (cf. AUTHORS.md). */ -/* */ -/* 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 "doc_data.h" - -#include "core/config/engine.h" -#include "core/config/project_settings.h" -#include "core/core_constants.h" -#include "core/io/compression.h" -#include "core/io/marshalls.h" -#include "core/object/script_language.h" -#include "core/os/dir_access.h" -#include "core/version.h" -#include "scene/resources/theme.h" - -// Used for a hack preserving Mono properties on non-Mono builds. -#include "modules/modules_enabled.gen.h" - -void DocData::merge_from(const DocData &p_data) { - for (Map::Element *E = class_list.front(); E; E = E->next()) { - ClassDoc &c = E->get(); - - if (!p_data.class_list.has(c.name)) { - continue; - } - - const ClassDoc &cf = p_data.class_list[c.name]; - - c.description = cf.description; - c.brief_description = cf.brief_description; - c.tutorials = cf.tutorials; - - for (int i = 0; i < c.methods.size(); i++) { - MethodDoc &m = c.methods.write[i]; - - for (int j = 0; j < cf.methods.size(); j++) { - if (cf.methods[j].name != m.name) { - continue; - } - if (cf.methods[j].arguments.size() != m.arguments.size()) { - continue; - } - // since polymorphic functions are allowed we need to check the type of - // the arguments so we make sure they are different. - int arg_count = cf.methods[j].arguments.size(); - Vector arg_used; - arg_used.resize(arg_count); - for (int l = 0; l < arg_count; ++l) { - arg_used.write[l] = false; - } - // also there is no guarantee that argument ordering will match, so we - // have to check one by one so we make sure we have an exact match - for (int k = 0; k < arg_count; ++k) { - for (int l = 0; l < arg_count; ++l) { - if (cf.methods[j].arguments[k].type == m.arguments[l].type && !arg_used[l]) { - arg_used.write[l] = true; - break; - } - } - } - bool not_the_same = false; - for (int l = 0; l < arg_count; ++l) { - if (!arg_used[l]) { // at least one of the arguments was different - not_the_same = true; - } - } - if (not_the_same) { - continue; - } - - const MethodDoc &mf = cf.methods[j]; - - m.description = mf.description; - break; - } - } - - for (int i = 0; i < c.signals.size(); i++) { - MethodDoc &m = c.signals.write[i]; - - for (int j = 0; j < cf.signals.size(); j++) { - if (cf.signals[j].name != m.name) { - continue; - } - const MethodDoc &mf = cf.signals[j]; - - m.description = mf.description; - break; - } - } - - for (int i = 0; i < c.constants.size(); i++) { - ConstantDoc &m = c.constants.write[i]; - - for (int j = 0; j < cf.constants.size(); j++) { - if (cf.constants[j].name != m.name) { - continue; - } - const ConstantDoc &mf = cf.constants[j]; - - m.description = mf.description; - break; - } - } - - for (int i = 0; i < c.properties.size(); i++) { - PropertyDoc &p = c.properties.write[i]; - - for (int j = 0; j < cf.properties.size(); j++) { - if (cf.properties[j].name != p.name) { - continue; - } - const PropertyDoc &pf = cf.properties[j]; - - p.description = pf.description; - break; - } - } - - for (int i = 0; i < c.theme_properties.size(); i++) { - PropertyDoc &p = c.theme_properties.write[i]; - - for (int j = 0; j < cf.theme_properties.size(); j++) { - if (cf.theme_properties[j].name != p.name) { - continue; - } - const PropertyDoc &pf = cf.theme_properties[j]; - - p.description = pf.description; - break; - } - } - -#ifndef MODULE_MONO_ENABLED - // The Mono module defines some properties that we want to keep when - // re-generating docs with a non-Mono build, to prevent pointless diffs - // (and loss of descriptions) depending on the config of the doc writer. - // We use a horrible hack to force keeping the relevant properties, - // hardcoded below. At least it's an ad hoc hack... ¯\_(ツ)_/¯ - // Don't show this to your kids. - if (c.name == "@GlobalScope") { - // Retrieve GodotSharp singleton. - for (int j = 0; j < cf.properties.size(); j++) { - if (cf.properties[j].name == "GodotSharp") { - c.properties.push_back(cf.properties[j]); - } - } - } -#endif - } -} - -void DocData::remove_from(const DocData &p_data) { - for (Map::Element *E = p_data.class_list.front(); E; E = E->next()) { - if (class_list.has(E->key())) { - class_list.erase(E->key()); - } - } -} - -void DocData::add_doc(const ClassDoc &p_class_doc) { - ERR_FAIL_COND(p_class_doc.name == ""); - class_list[p_class_doc.name] = p_class_doc; -} - -void DocData::remove_doc(const String &p_class_name) { - ERR_FAIL_COND(p_class_name == "" || !class_list.has(p_class_name)); - class_list.erase(p_class_name); -} - -bool DocData::has_doc(const String &p_class_name) { - if (p_class_name == "") { - return false; - } - return class_list.has(p_class_name); -} - -void DocData::return_doc_from_retinfo(DocData::MethodDoc &p_method, const PropertyInfo &p_retinfo) { - if (p_retinfo.type == Variant::INT && p_retinfo.usage & PROPERTY_USAGE_CLASS_IS_ENUM) { - p_method.return_enum = p_retinfo.class_name; - if (p_method.return_enum.begins_with("_")) { //proxy class - p_method.return_enum = p_method.return_enum.substr(1, p_method.return_enum.length()); - } - p_method.return_type = "int"; - } else if (p_retinfo.class_name != StringName()) { - p_method.return_type = p_retinfo.class_name; - } else if (p_retinfo.type == Variant::ARRAY && p_retinfo.hint == PROPERTY_HINT_ARRAY_TYPE) { - p_method.return_type = p_retinfo.hint_string + "[]"; - } else if (p_retinfo.hint == PROPERTY_HINT_RESOURCE_TYPE) { - p_method.return_type = p_retinfo.hint_string; - } else if (p_retinfo.type == Variant::NIL && p_retinfo.usage & PROPERTY_USAGE_NIL_IS_VARIANT) { - p_method.return_type = "Variant"; - } else if (p_retinfo.type == Variant::NIL) { - p_method.return_type = "void"; - } else { - p_method.return_type = Variant::get_type_name(p_retinfo.type); - } -} - -void DocData::argument_doc_from_arginfo(DocData::ArgumentDoc &p_argument, const PropertyInfo &p_arginfo) { - p_argument.name = p_arginfo.name; - - if (p_arginfo.type == Variant::INT && p_arginfo.usage & PROPERTY_USAGE_CLASS_IS_ENUM) { - p_argument.enumeration = p_arginfo.class_name; - if (p_argument.enumeration.begins_with("_")) { //proxy class - p_argument.enumeration = p_argument.enumeration.substr(1, p_argument.enumeration.length()); - } - p_argument.type = "int"; - } else if (p_arginfo.class_name != StringName()) { - p_argument.type = p_arginfo.class_name; - } else if (p_arginfo.type == Variant::ARRAY && p_arginfo.hint == PROPERTY_HINT_ARRAY_TYPE) { - p_argument.type = p_arginfo.hint_string + "[]"; - } else if (p_arginfo.hint == PROPERTY_HINT_RESOURCE_TYPE) { - p_argument.type = p_arginfo.hint_string; - } else if (p_arginfo.type == Variant::NIL) { - // Parameters cannot be void, so PROPERTY_USAGE_NIL_IS_VARIANT is not necessary - p_argument.type = "Variant"; - } else { - p_argument.type = Variant::get_type_name(p_arginfo.type); - } -} - -void DocData::property_doc_from_scriptmemberinfo(DocData::PropertyDoc &p_property, const ScriptMemberInfo &p_memberinfo) { - p_property.name = p_memberinfo.propinfo.name; - p_property.description = p_memberinfo.doc_string; - - if (p_memberinfo.propinfo.type == Variant::OBJECT) { - p_property.type = p_memberinfo.propinfo.class_name; - } else if (p_memberinfo.propinfo.type == Variant::NIL && p_memberinfo.propinfo.usage & PROPERTY_USAGE_NIL_IS_VARIANT) { - p_property.type = "Variant"; - } else { - p_property.type = Variant::get_type_name(p_memberinfo.propinfo.type); - } - - p_property.setter = p_memberinfo.setter; - p_property.getter = p_memberinfo.getter; - - if (p_memberinfo.has_default_value && p_memberinfo.default_value.get_type() != Variant::OBJECT) { - p_property.default_value = p_memberinfo.default_value.get_construct_string().replace("\n", ""); - } - - p_property.overridden = false; -} - -void DocData::method_doc_from_methodinfo(DocData::MethodDoc &p_method, const MethodInfo &p_methodinfo, const String &p_desc) { - p_method.name = p_methodinfo.name; - p_method.description = p_desc; - - return_doc_from_retinfo(p_method, p_methodinfo.return_val); - - for (int i = 0; i < p_methodinfo.arguments.size(); i++) { - ArgumentDoc argument; - argument_doc_from_arginfo(argument, p_methodinfo.arguments[i]); - int default_arg_index = i - (p_methodinfo.arguments.size() - p_methodinfo.default_arguments.size()); - if (default_arg_index >= 0) { - Variant default_arg = p_methodinfo.default_arguments[default_arg_index]; - argument.default_value = default_arg.get_construct_string(); - } - p_method.arguments.push_back(argument); - } -} - -void DocData::constant_doc_from_variant(DocData::ConstantDoc &p_const, const StringName &p_name, const Variant &p_value, const String &p_desc) { - p_const.name = p_name; - p_const.value = p_value; - p_const.description = p_desc; -} - -void DocData::signal_doc_from_methodinfo(DocData::MethodDoc &p_signal, const MethodInfo &p_methodinfo, const String &p_desc) { - return method_doc_from_methodinfo(p_signal, p_methodinfo, p_desc); -} - -static Variant get_documentation_default_value(const StringName &p_class_name, const StringName &p_property_name, bool &r_default_value_valid) { - Variant default_value = Variant(); - r_default_value_valid = false; - - if (ClassDB::can_instance(p_class_name)) { - default_value = ClassDB::class_get_default_property_value(p_class_name, p_property_name, &r_default_value_valid); - } else { - // Cannot get default value of classes that can't be instanced - List inheriting_classes; - ClassDB::get_direct_inheriters_from_class(p_class_name, &inheriting_classes); - for (List::Element *E2 = inheriting_classes.front(); E2; E2 = E2->next()) { - if (ClassDB::can_instance(E2->get())) { - default_value = ClassDB::class_get_default_property_value(E2->get(), p_property_name, &r_default_value_valid); - if (r_default_value_valid) { - break; - } - } - } - } - - return default_value; -} - -void DocData::generate(bool p_basic_types) { - List classes; - ClassDB::get_class_list(&classes); - classes.sort_custom(); - // Move ProjectSettings, so that other classes can register properties there. - classes.move_to_back(classes.find("ProjectSettings")); - - bool skip_setter_getter_methods = true; - - while (classes.size()) { - Set setters_getters; - - String name = classes.front()->get(); - if (!ClassDB::is_class_exposed(name)) { - print_verbose(vformat("Class '%s' is not exposed, skipping.", name)); - classes.pop_front(); - continue; - } - - String cname = name; - if (cname.begins_with("_")) { //proxy class - cname = cname.substr(1, name.length()); - } - - class_list[cname] = ClassDoc(); - ClassDoc &c = class_list[cname]; - c.name = cname; - c.inherits = ClassDB::get_parent_class(name); - - List properties; - List own_properties; - if (name == "ProjectSettings") { - //special case for project settings, so settings can be documented - ProjectSettings::get_singleton()->get_property_list(&properties); - own_properties = properties; - } else { - ClassDB::get_property_list(name, &properties); - ClassDB::get_property_list(name, &own_properties, true); - } - - List::Element *EO = own_properties.front(); - for (List::Element *E = properties.front(); E; E = E->next()) { - bool inherited = EO == nullptr; - if (EO && EO->get() == E->get()) { - inherited = false; - EO = EO->next(); - } - - if (E->get().usage & PROPERTY_USAGE_GROUP || E->get().usage & PROPERTY_USAGE_SUBGROUP || E->get().usage & PROPERTY_USAGE_CATEGORY || E->get().usage & PROPERTY_USAGE_INTERNAL) { - continue; - } - - PropertyDoc prop; - - prop.name = E->get().name; - - prop.overridden = inherited; - - bool default_value_valid = false; - Variant default_value; - - if (name == "ProjectSettings") { - // Special case for project settings, so that settings are not taken from the current project's settings - if (E->get().name == "script" || !ProjectSettings::get_singleton()->is_builtin_setting(E->get().name)) { - continue; - } - if (E->get().usage & PROPERTY_USAGE_EDITOR) { - if (!ProjectSettings::get_singleton()->get_ignore_value_in_docs(E->get().name)) { - default_value = ProjectSettings::get_singleton()->property_get_revert(E->get().name); - default_value_valid = true; - } - } - } else { - default_value = get_documentation_default_value(name, E->get().name, default_value_valid); - if (inherited) { - bool base_default_value_valid = false; - Variant base_default_value = get_documentation_default_value(ClassDB::get_parent_class(name), E->get().name, base_default_value_valid); - if (!default_value_valid || !base_default_value_valid || default_value == base_default_value) { - continue; - } - } - } - - //used to track uninitialized values using valgrind - //print_line("getting default value for " + String(name) + "." + String(E->get().name)); - if (default_value_valid && default_value.get_type() != Variant::OBJECT) { - prop.default_value = default_value.get_construct_string().replace("\n", ""); - } - - StringName setter = ClassDB::get_property_setter(name, E->get().name); - StringName getter = ClassDB::get_property_getter(name, E->get().name); - - prop.setter = setter; - prop.getter = getter; - - bool found_type = false; - if (getter != StringName()) { - MethodBind *mb = ClassDB::get_method(name, getter); - if (mb) { - PropertyInfo retinfo = mb->get_return_info(); - - found_type = true; - if (retinfo.type == Variant::INT && retinfo.usage & PROPERTY_USAGE_CLASS_IS_ENUM) { - prop.enumeration = retinfo.class_name; - prop.type = "int"; - } else if (retinfo.class_name != StringName()) { - prop.type = retinfo.class_name; - } else if (retinfo.type == Variant::ARRAY && retinfo.hint == PROPERTY_HINT_ARRAY_TYPE) { - prop.type = retinfo.hint_string + "[]"; - } else if (retinfo.hint == PROPERTY_HINT_RESOURCE_TYPE) { - prop.type = retinfo.hint_string; - } else if (retinfo.type == Variant::NIL && retinfo.usage & PROPERTY_USAGE_NIL_IS_VARIANT) { - prop.type = "Variant"; - } else if (retinfo.type == Variant::NIL) { - prop.type = "void"; - } else { - prop.type = Variant::get_type_name(retinfo.type); - } - } - - setters_getters.insert(getter); - } - - if (setter != StringName()) { - setters_getters.insert(setter); - } - - if (!found_type) { - if (E->get().type == Variant::OBJECT && E->get().hint == PROPERTY_HINT_RESOURCE_TYPE) { - prop.type = E->get().hint_string; - } else { - prop.type = Variant::get_type_name(E->get().type); - } - } - - c.properties.push_back(prop); - } - - List method_list; - ClassDB::get_method_list(name, &method_list, true); - method_list.sort(); - - for (List::Element *E = method_list.front(); E; E = E->next()) { - if (E->get().name == "" || (E->get().name[0] == '_' && !(E->get().flags & METHOD_FLAG_VIRTUAL))) { - continue; //hidden, don't count - } - - if (skip_setter_getter_methods && setters_getters.has(E->get().name)) { - // Don't skip parametric setters and getters, i.e. method which require - // one or more parameters to define what property should be set or retrieved. - // E.g. CPUParticles3D::set_param(Parameter param, float value). - if (E->get().arguments.size() == 0 /* getter */ || (E->get().arguments.size() == 1 && E->get().return_val.type == Variant::NIL /* setter */)) { - continue; - } - } - - MethodDoc method; - - method.name = E->get().name; - - if (E->get().flags & METHOD_FLAG_VIRTUAL) { - method.qualifiers = "virtual"; - } - - if (E->get().flags & METHOD_FLAG_CONST) { - if (method.qualifiers != "") { - method.qualifiers += " "; - } - method.qualifiers += "const"; - } else if (E->get().flags & METHOD_FLAG_VARARG) { - if (method.qualifiers != "") { - method.qualifiers += " "; - } - method.qualifiers += "vararg"; - } - - for (int i = -1; i < E->get().arguments.size(); i++) { - if (i == -1) { -#ifdef DEBUG_METHODS_ENABLED - return_doc_from_retinfo(method, E->get().return_val); -#endif - } else { - const PropertyInfo &arginfo = E->get().arguments[i]; - ArgumentDoc argument; - argument_doc_from_arginfo(argument, arginfo); - - int darg_idx = i - (E->get().arguments.size() - E->get().default_arguments.size()); - if (darg_idx >= 0) { - Variant default_arg = E->get().default_arguments[darg_idx]; - argument.default_value = default_arg.get_construct_string(); - } - - method.arguments.push_back(argument); - } - } - - c.methods.push_back(method); - } - - List signal_list; - ClassDB::get_signal_list(name, &signal_list, true); - - if (signal_list.size()) { - for (List::Element *EV = signal_list.front(); EV; EV = EV->next()) { - MethodDoc signal; - signal.name = EV->get().name; - for (int i = 0; i < EV->get().arguments.size(); i++) { - const PropertyInfo &arginfo = EV->get().arguments[i]; - ArgumentDoc argument; - argument_doc_from_arginfo(argument, arginfo); - - signal.arguments.push_back(argument); - } - - c.signals.push_back(signal); - } - } - - List constant_list; - ClassDB::get_integer_constant_list(name, &constant_list, true); - - for (List::Element *E = constant_list.front(); E; E = E->next()) { - ConstantDoc constant; - constant.name = E->get(); - constant.value = itos(ClassDB::get_integer_constant(name, E->get())); - constant.is_value_valid = true; - constant.enumeration = ClassDB::get_integer_constant_enum(name, E->get()); - c.constants.push_back(constant); - } - - //theme stuff - - { - List l; - Theme::get_default()->get_constant_list(cname, &l); - for (List::Element *E = l.front(); E; E = E->next()) { - PropertyDoc pd; - pd.name = E->get(); - pd.type = "int"; - pd.default_value = itos(Theme::get_default()->get_constant(E->get(), cname)); - c.theme_properties.push_back(pd); - } - - l.clear(); - Theme::get_default()->get_color_list(cname, &l); - for (List::Element *E = l.front(); E; E = E->next()) { - PropertyDoc pd; - pd.name = E->get(); - pd.type = "Color"; - pd.default_value = Variant(Theme::get_default()->get_color(E->get(), cname)).get_construct_string(); - c.theme_properties.push_back(pd); - } - - l.clear(); - Theme::get_default()->get_icon_list(cname, &l); - for (List::Element *E = l.front(); E; E = E->next()) { - PropertyDoc pd; - pd.name = E->get(); - pd.type = "Texture2D"; - c.theme_properties.push_back(pd); - } - l.clear(); - Theme::get_default()->get_font_list(cname, &l); - for (List::Element *E = l.front(); E; E = E->next()) { - PropertyDoc pd; - pd.name = E->get(); - pd.type = "Font"; - c.theme_properties.push_back(pd); - } - l.clear(); - Theme::get_default()->get_font_size_list(cname, &l); - for (List::Element *E = l.front(); E; E = E->next()) { - PropertyDoc pd; - pd.name = E->get(); - pd.type = "int"; - c.theme_properties.push_back(pd); - } - l.clear(); - Theme::get_default()->get_stylebox_list(cname, &l); - for (List::Element *E = l.front(); E; E = E->next()) { - PropertyDoc pd; - pd.name = E->get(); - pd.type = "StyleBox"; - c.theme_properties.push_back(pd); - } - } - - classes.pop_front(); - } - - { - // So we can document the concept of Variant even if it's not a usable class per se. - class_list["Variant"] = ClassDoc(); - class_list["Variant"].name = "Variant"; - } - - if (!p_basic_types) { - return; - } - - // Add Variant types. - for (int i = 0; i < Variant::VARIANT_MAX; i++) { - if (i == Variant::NIL) { - continue; // Not exposed outside of 'null', should not be in class list. - } - if (i == Variant::OBJECT) { - continue; // Use the core type instead. - } - - String cname = Variant::get_type_name(Variant::Type(i)); - - class_list[cname] = ClassDoc(); - ClassDoc &c = class_list[cname]; - c.name = cname; - - Callable::CallError cerror; - Variant v; - Variant::construct(Variant::Type(i), v, nullptr, 0, cerror); - - List method_list; - v.get_method_list(&method_list); - method_list.sort(); - Variant::get_constructor_list(Variant::Type(i), &method_list); - - for (int j = 0; j < Variant::OP_AND; j++) { // Showing above 'and' is pretty confusing and there are a lot of variations. - for (int k = 0; k < Variant::VARIANT_MAX; k++) { - Variant::Type rt = Variant::get_operator_return_type(Variant::Operator(j), Variant::Type(i), Variant::Type(k)); - if (rt != Variant::NIL) { // Has operator. - // Skip String % operator as it's registered separately for each Variant arg type, - // we'll add it manually below. - if (i == Variant::STRING && Variant::Operator(j) == Variant::OP_MODULE) { - continue; - } - MethodInfo mi; - mi.name = "operator " + Variant::get_operator_name(Variant::Operator(j)); - mi.return_val.type = rt; - if (k != Variant::NIL) { - PropertyInfo arg; - arg.name = "right"; - arg.type = Variant::Type(k); - mi.arguments.push_back(arg); - } - method_list.push_back(mi); - } - } - } - - if (i == Variant::STRING) { - // We skipped % operator above, and we register it manually once for Variant arg type here. - MethodInfo mi; - mi.name = "operator %"; - mi.return_val.type = Variant::STRING; - - PropertyInfo arg; - arg.name = "right"; - arg.type = Variant::NIL; - arg.usage = PROPERTY_USAGE_NIL_IS_VARIANT; - mi.arguments.push_back(arg); - - method_list.push_back(mi); - } - - if (Variant::is_keyed(Variant::Type(i))) { - MethodInfo mi; - mi.name = "operator []"; - mi.return_val.type = Variant::NIL; - mi.return_val.usage = PROPERTY_USAGE_NIL_IS_VARIANT; - - PropertyInfo arg; - arg.name = "key"; - arg.type = Variant::NIL; - arg.usage = PROPERTY_USAGE_NIL_IS_VARIANT; - mi.arguments.push_back(arg); - - method_list.push_back(mi); - } else if (Variant::has_indexing(Variant::Type(i))) { - MethodInfo mi; - mi.name = "operator []"; - mi.return_val.type = Variant::get_indexed_element_type(Variant::Type(i)); - PropertyInfo arg; - arg.name = "index"; - arg.type = Variant::INT; - mi.arguments.push_back(arg); - - method_list.push_back(mi); - } - - for (List::Element *E = method_list.front(); E; E = E->next()) { - MethodInfo &mi = E->get(); - MethodDoc method; - - method.name = mi.name; - if (method.name == cname) { - method.qualifiers = "constructor"; - } else if (method.name.begins_with("operator")) { - method.qualifiers = "operator"; - } - - for (int j = 0; j < mi.arguments.size(); j++) { - PropertyInfo arginfo = mi.arguments[j]; - ArgumentDoc ad; - argument_doc_from_arginfo(ad, mi.arguments[j]); - ad.name = arginfo.name; - - int darg_idx = mi.default_arguments.size() - mi.arguments.size() + j; - if (darg_idx >= 0) { - Variant default_arg = mi.default_arguments[darg_idx]; - ad.default_value = default_arg.get_construct_string(); - } - - method.arguments.push_back(ad); - } - - return_doc_from_retinfo(method, mi.return_val); - - if (mi.flags & METHOD_FLAG_VARARG) { - if (method.qualifiers != "") { - method.qualifiers += " "; - } - method.qualifiers += "vararg"; - } - - c.methods.push_back(method); - } - - List properties; - v.get_property_list(&properties); - for (List::Element *E = properties.front(); E; E = E->next()) { - PropertyInfo pi = E->get(); - PropertyDoc property; - property.name = pi.name; - property.type = Variant::get_type_name(pi.type); - property.default_value = v.get(pi.name).get_construct_string(); - - c.properties.push_back(property); - } - - List constants; - Variant::get_constants_for_type(Variant::Type(i), &constants); - - for (List::Element *E = constants.front(); E; E = E->next()) { - ConstantDoc constant; - constant.name = E->get(); - Variant value = Variant::get_constant_value(Variant::Type(i), E->get()); - constant.value = value.get_type() == Variant::INT ? itos(value) : value.get_construct_string(); - constant.is_value_valid = true; - c.constants.push_back(constant); - } - } - - //built in constants and functions - - { - String cname = "@GlobalScope"; - class_list[cname] = ClassDoc(); - ClassDoc &c = class_list[cname]; - c.name = cname; - - for (int i = 0; i < CoreConstants::get_global_constant_count(); i++) { - ConstantDoc cd; - cd.name = CoreConstants::get_global_constant_name(i); - if (!CoreConstants::get_ignore_value_in_docs(i)) { - cd.value = itos(CoreConstants::get_global_constant_value(i)); - cd.is_value_valid = true; - } else { - cd.is_value_valid = false; - } - cd.enumeration = CoreConstants::get_global_constant_enum(i); - c.constants.push_back(cd); - } - - List singletons; - Engine::get_singleton()->get_singletons(&singletons); - - //servers (this is kind of hackish) - for (List::Element *E = singletons.front(); E; E = E->next()) { - PropertyDoc pd; - Engine::Singleton &s = E->get(); - if (!s.ptr) { - continue; - } - pd.name = s.name; - pd.type = s.ptr->get_class(); - while (String(ClassDB::get_parent_class(pd.type)) != "Object") { - pd.type = ClassDB::get_parent_class(pd.type); - } - if (pd.type.begins_with("_")) { - pd.type = pd.type.substr(1, pd.type.length()); - } - c.properties.push_back(pd); - } - - List utility_functions; - Variant::get_utility_function_list(&utility_functions); - utility_functions.sort_custom(); - for (List::Element *E = utility_functions.front(); E; E = E->next()) { - MethodDoc md; - md.name = E->get(); - //return - if (Variant::has_utility_function_return_value(E->get())) { - PropertyInfo pi; - pi.type = Variant::get_utility_function_return_type(E->get()); - if (pi.type == Variant::NIL) { - pi.usage = PROPERTY_USAGE_NIL_IS_VARIANT; - } - DocData::ArgumentDoc ad; - argument_doc_from_arginfo(ad, pi); - md.return_type = ad.type; - } - - if (Variant::is_utility_function_vararg(E->get())) { - md.qualifiers = "vararg"; - } else { - for (int i = 0; i < Variant::get_utility_function_argument_count(E->get()); i++) { - PropertyInfo pi; - pi.type = Variant::get_utility_function_argument_type(E->get(), i); - pi.name = Variant::get_utility_function_argument_name(E->get(), i); - if (pi.type == Variant::NIL) { - pi.usage = PROPERTY_USAGE_NIL_IS_VARIANT; - } - DocData::ArgumentDoc ad; - argument_doc_from_arginfo(ad, pi); - md.arguments.push_back(ad); - } - } - - c.methods.push_back(md); - } - } - - // Built-in script reference. - // We only add a doc entry for languages which actually define any built-in - // methods or constants. - - { - for (int i = 0; i < ScriptServer::get_language_count(); i++) { - ScriptLanguage *lang = ScriptServer::get_language(i); - String cname = "@" + lang->get_name(); - ClassDoc c; - c.name = cname; - - // Get functions. - List minfo; - lang->get_public_functions(&minfo); - - for (List::Element *E = minfo.front(); E; E = E->next()) { - MethodInfo &mi = E->get(); - MethodDoc md; - md.name = mi.name; - - if (mi.flags & METHOD_FLAG_VARARG) { - if (md.qualifiers != "") { - md.qualifiers += " "; - } - md.qualifiers += "vararg"; - } - - return_doc_from_retinfo(md, mi.return_val); - - for (int j = 0; j < mi.arguments.size(); j++) { - ArgumentDoc ad; - argument_doc_from_arginfo(ad, mi.arguments[j]); - - int darg_idx = j - (mi.arguments.size() - mi.default_arguments.size()); - if (darg_idx >= 0) { - Variant default_arg = E->get().default_arguments[darg_idx]; - ad.default_value = default_arg.get_construct_string(); - } - - md.arguments.push_back(ad); - } - - c.methods.push_back(md); - } - - // Get constants. - List> cinfo; - lang->get_public_constants(&cinfo); - - for (List>::Element *E = cinfo.front(); E; E = E->next()) { - ConstantDoc cd; - cd.name = E->get().first; - cd.value = E->get().second; - cd.is_value_valid = true; - c.constants.push_back(cd); - } - - // Skip adding the lang if it doesn't expose anything (e.g. C#). - if (c.methods.empty() && c.constants.empty()) { - continue; - } - - class_list[cname] = c; - } - } -} - -static Error _parse_methods(Ref &parser, Vector &methods) { - String section = parser->get_node_name(); - String element = section.substr(0, section.length() - 1); - - while (parser->read() == OK) { - if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { - if (parser->get_node_name() == element) { - DocData::MethodDoc method; - ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); - method.name = parser->get_attribute_value("name"); - if (parser->has_attribute("qualifiers")) { - method.qualifiers = parser->get_attribute_value("qualifiers"); - } - - while (parser->read() == OK) { - if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { - String name = parser->get_node_name(); - if (name == "return") { - ERR_FAIL_COND_V(!parser->has_attribute("type"), ERR_FILE_CORRUPT); - method.return_type = parser->get_attribute_value("type"); - if (parser->has_attribute("enum")) { - method.return_enum = parser->get_attribute_value("enum"); - } - } else if (name == "argument") { - DocData::ArgumentDoc argument; - ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); - argument.name = parser->get_attribute_value("name"); - ERR_FAIL_COND_V(!parser->has_attribute("type"), ERR_FILE_CORRUPT); - argument.type = parser->get_attribute_value("type"); - if (parser->has_attribute("enum")) { - argument.enumeration = parser->get_attribute_value("enum"); - } - - method.arguments.push_back(argument); - - } else if (name == "description") { - parser->read(); - if (parser->get_node_type() == XMLParser::NODE_TEXT) { - method.description = parser->get_node_data(); - } - } - - } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == element) { - break; - } - } - - methods.push_back(method); - - } else { - ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + parser->get_node_name() + "."); - } - - } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == section) { - break; - } - } - - return OK; -} - -Error DocData::load_classes(const String &p_dir) { - Error err; - DirAccessRef da = DirAccess::open(p_dir, &err); - if (!da) { - return err; - } - - da->list_dir_begin(); - String path; - path = da->get_next(); - while (path != String()) { - if (!da->current_is_dir() && path.ends_with("xml")) { - Ref parser = memnew(XMLParser); - Error err2 = parser->open(p_dir.plus_file(path)); - if (err2) { - return err2; - } - - _load(parser); - } - path = da->get_next(); - } - - da->list_dir_end(); - - return OK; -} - -Error DocData::erase_classes(const String &p_dir) { - Error err; - DirAccessRef da = DirAccess::open(p_dir, &err); - if (!da) { - return err; - } - - List to_erase; - - da->list_dir_begin(); - String path; - path = da->get_next(); - while (path != String()) { - if (!da->current_is_dir() && path.ends_with("xml")) { - to_erase.push_back(path); - } - path = da->get_next(); - } - da->list_dir_end(); - - while (to_erase.size()) { - da->remove(to_erase.front()->get()); - to_erase.pop_front(); - } - - return OK; -} - -Error DocData::_load(Ref parser) { - Error err = OK; - - while ((err = parser->read()) == OK) { - if (parser->get_node_type() == XMLParser::NODE_ELEMENT && parser->get_node_name() == "?xml") { - parser->skip_section(); - } - - if (parser->get_node_type() != XMLParser::NODE_ELEMENT) { - continue; //no idea what this may be, but skipping anyway - } - - ERR_FAIL_COND_V(parser->get_node_name() != "class", ERR_FILE_CORRUPT); - - ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); - String name = parser->get_attribute_value("name"); - class_list[name] = ClassDoc(); - ClassDoc &c = class_list[name]; - - c.name = name; - if (parser->has_attribute("inherits")) { - c.inherits = parser->get_attribute_value("inherits"); - } - - while (parser->read() == OK) { - if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { - String name2 = parser->get_node_name(); - - if (name2 == "brief_description") { - parser->read(); - if (parser->get_node_type() == XMLParser::NODE_TEXT) { - c.brief_description = parser->get_node_data(); - } - - } else if (name2 == "description") { - parser->read(); - if (parser->get_node_type() == XMLParser::NODE_TEXT) { - c.description = parser->get_node_data(); - } - } else if (name2 == "tutorials") { - while (parser->read() == OK) { - if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { - String name3 = parser->get_node_name(); - - if (name3 == "link") { - TutorialDoc tutorial; - if (parser->has_attribute("title")) { - tutorial.title = parser->get_attribute_value("title"); - } - parser->read(); - if (parser->get_node_type() == XMLParser::NODE_TEXT) { - tutorial.link = parser->get_node_data().strip_edges(); - c.tutorials.push_back(tutorial); - } - } else { - ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + name3 + "."); - } - } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == "tutorials") { - break; // End of . - } - } - } else if (name2 == "methods") { - Error err2 = _parse_methods(parser, c.methods); - ERR_FAIL_COND_V(err2, err2); - - } else if (name2 == "signals") { - Error err2 = _parse_methods(parser, c.signals); - ERR_FAIL_COND_V(err2, err2); - } else if (name2 == "members") { - while (parser->read() == OK) { - if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { - String name3 = parser->get_node_name(); - - if (name3 == "member") { - PropertyDoc prop2; - - ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); - prop2.name = parser->get_attribute_value("name"); - ERR_FAIL_COND_V(!parser->has_attribute("type"), ERR_FILE_CORRUPT); - prop2.type = parser->get_attribute_value("type"); - if (parser->has_attribute("setter")) { - prop2.setter = parser->get_attribute_value("setter"); - } - if (parser->has_attribute("getter")) { - prop2.getter = parser->get_attribute_value("getter"); - } - if (parser->has_attribute("enum")) { - prop2.enumeration = parser->get_attribute_value("enum"); - } - if (!parser->is_empty()) { - parser->read(); - if (parser->get_node_type() == XMLParser::NODE_TEXT) { - prop2.description = parser->get_node_data(); - } - } - c.properties.push_back(prop2); - } else { - ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + name3 + "."); - } - - } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == "members") { - break; // End of . - } - } - - } else if (name2 == "theme_items") { - while (parser->read() == OK) { - if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { - String name3 = parser->get_node_name(); - - if (name3 == "theme_item") { - PropertyDoc prop2; - - ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); - prop2.name = parser->get_attribute_value("name"); - ERR_FAIL_COND_V(!parser->has_attribute("type"), ERR_FILE_CORRUPT); - prop2.type = parser->get_attribute_value("type"); - if (!parser->is_empty()) { - parser->read(); - if (parser->get_node_type() == XMLParser::NODE_TEXT) { - prop2.description = parser->get_node_data(); - } - } - c.theme_properties.push_back(prop2); - } else { - ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + name3 + "."); - } - - } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == "theme_items") { - break; // End of . - } - } - - } else if (name2 == "constants") { - while (parser->read() == OK) { - if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { - String name3 = parser->get_node_name(); - - if (name3 == "constant") { - ConstantDoc constant2; - ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); - constant2.name = parser->get_attribute_value("name"); - ERR_FAIL_COND_V(!parser->has_attribute("value"), ERR_FILE_CORRUPT); - constant2.value = parser->get_attribute_value("value"); - constant2.is_value_valid = true; - if (parser->has_attribute("enum")) { - constant2.enumeration = parser->get_attribute_value("enum"); - } - if (!parser->is_empty()) { - parser->read(); - if (parser->get_node_type() == XMLParser::NODE_TEXT) { - constant2.description = parser->get_node_data(); - } - } - c.constants.push_back(constant2); - } else { - ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + name3 + "."); - } - - } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == "constants") { - break; // End of . - } - } - - } else { - ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + name2 + "."); - } - - } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == "class") { - break; // End of . - } - } - } - - return OK; -} - -static void _write_string(FileAccess *f, int p_tablevel, const String &p_string) { - if (p_string == "") { - return; - } - String tab; - for (int i = 0; i < p_tablevel; i++) { - tab += "\t"; - } - f->store_string(tab + p_string + "\n"); -} - -Error DocData::save_classes(const String &p_default_path, const Map &p_class_path) { - for (Map::Element *E = class_list.front(); E; E = E->next()) { - ClassDoc &c = E->get(); - - String save_path; - if (p_class_path.has(c.name)) { - save_path = p_class_path[c.name]; - } else { - save_path = p_default_path; - } - - Error err; - String save_file = save_path.plus_file(c.name + ".xml"); - FileAccessRef f = FileAccess::open(save_file, FileAccess::WRITE, &err); - - ERR_CONTINUE_MSG(err != OK, "Can't write doc file: " + save_file + "."); - - _write_string(f, 0, ""); - - String header = ""); - _write_string(f, 2, c.brief_description.strip_edges().xml_escape()); - _write_string(f, 1, ""); - - _write_string(f, 1, ""); - _write_string(f, 2, c.description.strip_edges().xml_escape()); - _write_string(f, 1, ""); - - _write_string(f, 1, ""); - for (int i = 0; i < c.tutorials.size(); i++) { - TutorialDoc tutorial = c.tutorials.get(i); - String title_attribute = (!tutorial.title.empty()) ? " title=\"" + tutorial.title.xml_escape() + "\"" : ""; - _write_string(f, 2, "" + tutorial.link.xml_escape() + ""); - } - _write_string(f, 1, ""); - - _write_string(f, 1, ""); - - c.methods.sort(); - - for (int i = 0; i < c.methods.size(); i++) { - const MethodDoc &m = c.methods[i]; - - String qualifiers; - if (m.qualifiers != "") { - qualifiers += " qualifiers=\"" + m.qualifiers.xml_escape() + "\""; - } - - _write_string(f, 2, ""); - - if (m.return_type != "") { - String enum_text; - if (m.return_enum != String()) { - enum_text = " enum=\"" + m.return_enum + "\""; - } - _write_string(f, 3, ""); - _write_string(f, 3, ""); - } - - for (int j = 0; j < m.arguments.size(); j++) { - const ArgumentDoc &a = m.arguments[j]; - - String enum_text; - if (a.enumeration != String()) { - enum_text = " enum=\"" + a.enumeration + "\""; - } - - if (a.default_value != "") { - _write_string(f, 3, ""); - } else { - _write_string(f, 3, ""); - } - - _write_string(f, 3, ""); - } - - _write_string(f, 3, ""); - _write_string(f, 4, m.description.strip_edges().xml_escape()); - _write_string(f, 3, ""); - - _write_string(f, 2, ""); - } - - _write_string(f, 1, ""); - - if (c.properties.size()) { - _write_string(f, 1, ""); - - c.properties.sort(); - - for (int i = 0; i < c.properties.size(); i++) { - String additional_attributes; - if (c.properties[i].enumeration != String()) { - additional_attributes += " enum=\"" + c.properties[i].enumeration + "\""; - } - if (c.properties[i].default_value != String()) { - additional_attributes += " default=\"" + c.properties[i].default_value.xml_escape(true) + "\""; - } - - const PropertyDoc &p = c.properties[i]; - - if (c.properties[i].overridden) { - _write_string(f, 2, ""); - } else { - _write_string(f, 2, ""); - _write_string(f, 3, p.description.strip_edges().xml_escape()); - _write_string(f, 2, ""); - } - } - _write_string(f, 1, ""); - } - - if (c.signals.size()) { - c.signals.sort(); - - _write_string(f, 1, ""); - for (int i = 0; i < c.signals.size(); i++) { - const MethodDoc &m = c.signals[i]; - _write_string(f, 2, ""); - for (int j = 0; j < m.arguments.size(); j++) { - const ArgumentDoc &a = m.arguments[j]; - _write_string(f, 3, ""); - _write_string(f, 3, ""); - } - - _write_string(f, 3, ""); - _write_string(f, 4, m.description.strip_edges().xml_escape()); - _write_string(f, 3, ""); - - _write_string(f, 2, ""); - } - - _write_string(f, 1, ""); - } - - _write_string(f, 1, ""); - - for (int i = 0; i < c.constants.size(); i++) { - const ConstantDoc &k = c.constants[i]; - if (k.is_value_valid) { - if (k.enumeration != String()) { - _write_string(f, 2, ""); - } else { - _write_string(f, 2, ""); - } - } else { - if (k.enumeration != String()) { - _write_string(f, 2, ""); - } else { - _write_string(f, 2, ""); - } - } - _write_string(f, 3, k.description.strip_edges().xml_escape()); - _write_string(f, 2, ""); - } - - _write_string(f, 1, ""); - - if (c.theme_properties.size()) { - c.theme_properties.sort(); - - _write_string(f, 1, ""); - for (int i = 0; i < c.theme_properties.size(); i++) { - const PropertyDoc &p = c.theme_properties[i]; - - if (p.default_value != "") { - _write_string(f, 2, ""); - } else { - _write_string(f, 2, ""); - } - - _write_string(f, 3, p.description.strip_edges().xml_escape()); - - _write_string(f, 2, ""); - } - _write_string(f, 1, ""); - } - - _write_string(f, 0, ""); - } - - return OK; -} - -Error DocData::load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size) { - Vector data; - data.resize(p_uncompressed_size); - Compression::decompress(data.ptrw(), p_uncompressed_size, p_data, p_compressed_size, Compression::MODE_DEFLATE); - class_list.clear(); - - Ref parser = memnew(XMLParser); - Error err = parser->open_buffer(data); - if (err) { - return err; - } - - _load(parser); - - return OK; -} diff --git a/editor/doc_data.h b/editor/doc_data.h deleted file mode 100644 index 0090a97c93..0000000000 --- a/editor/doc_data.h +++ /dev/null @@ -1,170 +0,0 @@ -/*************************************************************************/ -/* doc_data.h */ -/*************************************************************************/ -/* This file is part of: */ -/* GODOT ENGINE */ -/* https://godotengine.org */ -/*************************************************************************/ -/* Copyright (c) 2007-2020 Juan Linietsky, Ariel Manzur. */ -/* Copyright (c) 2014-2020 Godot Engine contributors (cf. AUTHORS.md). */ -/* */ -/* 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. */ -/*************************************************************************/ - -#ifndef DOC_DATA_H -#define DOC_DATA_H - -#include "core/io/xml_parser.h" -#include "core/templates/map.h" -#include "core/variant/variant.h" - -struct ScriptMemberInfo { - PropertyInfo propinfo; - String doc_string; - StringName setter; - StringName getter; - - bool has_default_value = false; - Variant default_value; -}; - -class DocData { -public: - struct ArgumentDoc { - String name; - String type; - String enumeration; - String default_value; - bool operator<(const ArgumentDoc &p_arg) const { - if (name == p_arg.name) { - return type < p_arg.type; - } - return name < p_arg.name; - } - }; - - struct MethodDoc { - String name; - String return_type; - String return_enum; - String qualifiers; - String description; - Vector arguments; - bool operator<(const MethodDoc &p_method) const { - if (name == p_method.name) { - // Must be a constructor since there is no overloading. - // We want this arbitrary order for a class "Foo": - // - 1. Default constructor: Foo() - // - 2. Copy constructor: Foo(Foo) - // - 3+. Other constructors Foo(Bar, ...) based on first argument's name - if (arguments.size() == 0 || p_method.arguments.size() == 0) { // 1. - return arguments.size() < p_method.arguments.size(); - } - if (arguments[0].type == return_type || p_method.arguments[0].type == p_method.return_type) { // 2. - return (arguments[0].type == return_type) || (p_method.arguments[0].type != p_method.return_type); - } - return arguments[0] < p_method.arguments[0]; - } - return name < p_method.name; - } - }; - - struct ConstantDoc { - String name; - String value; - bool is_value_valid; - String enumeration; - String description; - bool operator<(const ConstantDoc &p_const) const { - return name < p_const.name; - } - }; - - struct EnumDoc { - String name = "@unnamed_enum"; - String description; - Vector values; - }; - - struct PropertyDoc { - String name; - String type; - String enumeration; - String description; - String setter, getter; - String default_value; - bool overridden = false; - bool operator<(const PropertyDoc &p_prop) const { - return name < p_prop.name; - } - }; - - struct TutorialDoc { - String link; - String title; - }; - - struct ClassDoc { - String name; - String inherits; - String category; - String brief_description; - String description; - Vector tutorials; - Vector methods; - Vector signals; - Vector constants; - Map enums; - Vector properties; - Vector theme_properties; - bool is_script_doc = false; - String script_path; - bool operator<(const ClassDoc &p_class) const { - return name < p_class.name; - } - }; - - String version; - - Map class_list; - Error _load(Ref parser); - -public: - static void return_doc_from_retinfo(DocData::MethodDoc &p_method, const PropertyInfo &p_retinfo); - static void argument_doc_from_arginfo(DocData::ArgumentDoc &p_argument, const PropertyInfo &p_arginfo); - static void property_doc_from_scriptmemberinfo(DocData::PropertyDoc &p_property, const ScriptMemberInfo &p_memberinfo); - static void method_doc_from_methodinfo(DocData::MethodDoc &p_method, const MethodInfo &p_methodinfo, const String &p_desc); - static void constant_doc_from_variant(DocData::ConstantDoc &p_const, const StringName &p_name, const Variant &p_value, const String &p_desc); - static void signal_doc_from_methodinfo(DocData::MethodDoc &p_signal, const MethodInfo &p_methodinfo, const String &p_desc); - - void merge_from(const DocData &p_data); - void remove_from(const DocData &p_data); - void add_doc(const ClassDoc &p_class_doc); - void remove_doc(const String &p_class_name); - bool has_doc(const String &p_class_name); - void generate(bool p_basic_types = false); - Error load_classes(const String &p_dir); - static Error erase_classes(const String &p_dir); - Error save_classes(const String &p_default_path, const Map &p_class_path); - - Error load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size); -}; - -#endif // DOC_DATA_H diff --git a/editor/doc_tools.cpp b/editor/doc_tools.cpp new file mode 100644 index 0000000000..5ee9abb183 --- /dev/null +++ b/editor/doc_tools.cpp @@ -0,0 +1,1336 @@ +/*************************************************************************/ +/* doc_tools.cpp */ +/*************************************************************************/ +/* This file is part of: */ +/* GODOT ENGINE */ +/* https://godotengine.org */ +/*************************************************************************/ +/* Copyright (c) 2007-2020 Juan Linietsky, Ariel Manzur. */ +/* Copyright (c) 2014-2020 Godot Engine contributors (cf. AUTHORS.md). */ +/* */ +/* 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 "doc_tools.h" + +#include "core/config/engine.h" +#include "core/config/project_settings.h" +#include "core/core_constants.h" +#include "core/io/compression.h" +#include "core/io/marshalls.h" +#include "core/object/script_language.h" +#include "core/os/dir_access.h" +#include "core/version.h" +#include "scene/resources/theme.h" + +// Used for a hack preserving Mono properties on non-Mono builds. +#include "modules/modules_enabled.gen.h" + +void DocTools::merge_from(const DocTools &p_data) { + for (Map::Element *E = class_list.front(); E; E = E->next()) { + DocData::ClassDoc &c = E->get(); + + if (!p_data.class_list.has(c.name)) { + continue; + } + + const DocData::ClassDoc &cf = p_data.class_list[c.name]; + + c.description = cf.description; + c.brief_description = cf.brief_description; + c.tutorials = cf.tutorials; + + for (int i = 0; i < c.methods.size(); i++) { + DocData::MethodDoc &m = c.methods.write[i]; + + for (int j = 0; j < cf.methods.size(); j++) { + if (cf.methods[j].name != m.name) { + continue; + } + if (cf.methods[j].arguments.size() != m.arguments.size()) { + continue; + } + // since polymorphic functions are allowed we need to check the type of + // the arguments so we make sure they are different. + int arg_count = cf.methods[j].arguments.size(); + Vector arg_used; + arg_used.resize(arg_count); + for (int l = 0; l < arg_count; ++l) { + arg_used.write[l] = false; + } + // also there is no guarantee that argument ordering will match, so we + // have to check one by one so we make sure we have an exact match + for (int k = 0; k < arg_count; ++k) { + for (int l = 0; l < arg_count; ++l) { + if (cf.methods[j].arguments[k].type == m.arguments[l].type && !arg_used[l]) { + arg_used.write[l] = true; + break; + } + } + } + bool not_the_same = false; + for (int l = 0; l < arg_count; ++l) { + if (!arg_used[l]) { // at least one of the arguments was different + not_the_same = true; + } + } + if (not_the_same) { + continue; + } + + const DocData::MethodDoc &mf = cf.methods[j]; + + m.description = mf.description; + break; + } + } + + for (int i = 0; i < c.signals.size(); i++) { + DocData::MethodDoc &m = c.signals.write[i]; + + for (int j = 0; j < cf.signals.size(); j++) { + if (cf.signals[j].name != m.name) { + continue; + } + const DocData::MethodDoc &mf = cf.signals[j]; + + m.description = mf.description; + break; + } + } + + for (int i = 0; i < c.constants.size(); i++) { + DocData::ConstantDoc &m = c.constants.write[i]; + + for (int j = 0; j < cf.constants.size(); j++) { + if (cf.constants[j].name != m.name) { + continue; + } + const DocData::ConstantDoc &mf = cf.constants[j]; + + m.description = mf.description; + break; + } + } + + for (int i = 0; i < c.properties.size(); i++) { + DocData::PropertyDoc &p = c.properties.write[i]; + + for (int j = 0; j < cf.properties.size(); j++) { + if (cf.properties[j].name != p.name) { + continue; + } + const DocData::PropertyDoc &pf = cf.properties[j]; + + p.description = pf.description; + break; + } + } + + for (int i = 0; i < c.theme_properties.size(); i++) { + DocData::PropertyDoc &p = c.theme_properties.write[i]; + + for (int j = 0; j < cf.theme_properties.size(); j++) { + if (cf.theme_properties[j].name != p.name) { + continue; + } + const DocData::PropertyDoc &pf = cf.theme_properties[j]; + + p.description = pf.description; + break; + } + } + +#ifndef MODULE_MONO_ENABLED + // The Mono module defines some properties that we want to keep when + // re-generating docs with a non-Mono build, to prevent pointless diffs + // (and loss of descriptions) depending on the config of the doc writer. + // We use a horrible hack to force keeping the relevant properties, + // hardcoded below. At least it's an ad hoc hack... ¯\_(ツ)_/¯ + // Don't show this to your kids. + if (c.name == "@GlobalScope") { + // Retrieve GodotSharp singleton. + for (int j = 0; j < cf.properties.size(); j++) { + if (cf.properties[j].name == "GodotSharp") { + c.properties.push_back(cf.properties[j]); + } + } + } +#endif + } +} + +void DocTools::remove_from(const DocTools &p_data) { + for (Map::Element *E = p_data.class_list.front(); E; E = E->next()) { + if (class_list.has(E->key())) { + class_list.erase(E->key()); + } + } +} + +void DocTools::add_doc(const DocData::ClassDoc &p_class_doc) { + ERR_FAIL_COND(p_class_doc.name == ""); + class_list[p_class_doc.name] = p_class_doc; +} + +void DocTools::remove_doc(const String &p_class_name) { + ERR_FAIL_COND(p_class_name == "" || !class_list.has(p_class_name)); + class_list.erase(p_class_name); +} + +bool DocTools::has_doc(const String &p_class_name) { + if (p_class_name == "") { + return false; + } + return class_list.has(p_class_name); +} + +static Variant get_documentation_default_value(const StringName &p_class_name, const StringName &p_property_name, bool &r_default_value_valid) { + Variant default_value = Variant(); + r_default_value_valid = false; + + if (ClassDB::can_instance(p_class_name)) { + default_value = ClassDB::class_get_default_property_value(p_class_name, p_property_name, &r_default_value_valid); + } else { + // Cannot get default value of classes that can't be instanced + List inheriting_classes; + ClassDB::get_direct_inheriters_from_class(p_class_name, &inheriting_classes); + for (List::Element *E2 = inheriting_classes.front(); E2; E2 = E2->next()) { + if (ClassDB::can_instance(E2->get())) { + default_value = ClassDB::class_get_default_property_value(E2->get(), p_property_name, &r_default_value_valid); + if (r_default_value_valid) { + break; + } + } + } + } + + return default_value; +} + +void DocTools::generate(bool p_basic_types) { + List classes; + ClassDB::get_class_list(&classes); + classes.sort_custom(); + // Move ProjectSettings, so that other classes can register properties there. + classes.move_to_back(classes.find("ProjectSettings")); + + bool skip_setter_getter_methods = true; + + while (classes.size()) { + Set setters_getters; + + String name = classes.front()->get(); + if (!ClassDB::is_class_exposed(name)) { + print_verbose(vformat("Class '%s' is not exposed, skipping.", name)); + classes.pop_front(); + continue; + } + + String cname = name; + if (cname.begins_with("_")) { //proxy class + cname = cname.substr(1, name.length()); + } + + class_list[cname] = DocData::ClassDoc(); + DocData::ClassDoc &c = class_list[cname]; + c.name = cname; + c.inherits = ClassDB::get_parent_class(name); + + List properties; + List own_properties; + if (name == "ProjectSettings") { + //special case for project settings, so settings can be documented + ProjectSettings::get_singleton()->get_property_list(&properties); + own_properties = properties; + } else { + ClassDB::get_property_list(name, &properties); + ClassDB::get_property_list(name, &own_properties, true); + } + + List::Element *EO = own_properties.front(); + for (List::Element *E = properties.front(); E; E = E->next()) { + bool inherited = EO == nullptr; + if (EO && EO->get() == E->get()) { + inherited = false; + EO = EO->next(); + } + + if (E->get().usage & PROPERTY_USAGE_GROUP || E->get().usage & PROPERTY_USAGE_SUBGROUP || E->get().usage & PROPERTY_USAGE_CATEGORY || E->get().usage & PROPERTY_USAGE_INTERNAL) { + continue; + } + + DocData::PropertyDoc prop; + + prop.name = E->get().name; + + prop.overridden = inherited; + + bool default_value_valid = false; + Variant default_value; + + if (name == "ProjectSettings") { + // Special case for project settings, so that settings are not taken from the current project's settings + if (E->get().name == "script" || !ProjectSettings::get_singleton()->is_builtin_setting(E->get().name)) { + continue; + } + if (E->get().usage & PROPERTY_USAGE_EDITOR) { + if (!ProjectSettings::get_singleton()->get_ignore_value_in_docs(E->get().name)) { + default_value = ProjectSettings::get_singleton()->property_get_revert(E->get().name); + default_value_valid = true; + } + } + } else { + default_value = get_documentation_default_value(name, E->get().name, default_value_valid); + if (inherited) { + bool base_default_value_valid = false; + Variant base_default_value = get_documentation_default_value(ClassDB::get_parent_class(name), E->get().name, base_default_value_valid); + if (!default_value_valid || !base_default_value_valid || default_value == base_default_value) { + continue; + } + } + } + + //used to track uninitialized values using valgrind + //print_line("getting default value for " + String(name) + "." + String(E->get().name)); + if (default_value_valid && default_value.get_type() != Variant::OBJECT) { + prop.default_value = default_value.get_construct_string().replace("\n", ""); + } + + StringName setter = ClassDB::get_property_setter(name, E->get().name); + StringName getter = ClassDB::get_property_getter(name, E->get().name); + + prop.setter = setter; + prop.getter = getter; + + bool found_type = false; + if (getter != StringName()) { + MethodBind *mb = ClassDB::get_method(name, getter); + if (mb) { + PropertyInfo retinfo = mb->get_return_info(); + + found_type = true; + if (retinfo.type == Variant::INT && retinfo.usage & PROPERTY_USAGE_CLASS_IS_ENUM) { + prop.enumeration = retinfo.class_name; + prop.type = "int"; + } else if (retinfo.class_name != StringName()) { + prop.type = retinfo.class_name; + } else if (retinfo.type == Variant::ARRAY && retinfo.hint == PROPERTY_HINT_ARRAY_TYPE) { + prop.type = retinfo.hint_string + "[]"; + } else if (retinfo.hint == PROPERTY_HINT_RESOURCE_TYPE) { + prop.type = retinfo.hint_string; + } else if (retinfo.type == Variant::NIL && retinfo.usage & PROPERTY_USAGE_NIL_IS_VARIANT) { + prop.type = "Variant"; + } else if (retinfo.type == Variant::NIL) { + prop.type = "void"; + } else { + prop.type = Variant::get_type_name(retinfo.type); + } + } + + setters_getters.insert(getter); + } + + if (setter != StringName()) { + setters_getters.insert(setter); + } + + if (!found_type) { + if (E->get().type == Variant::OBJECT && E->get().hint == PROPERTY_HINT_RESOURCE_TYPE) { + prop.type = E->get().hint_string; + } else { + prop.type = Variant::get_type_name(E->get().type); + } + } + + c.properties.push_back(prop); + } + + List method_list; + ClassDB::get_method_list(name, &method_list, true); + method_list.sort(); + + for (List::Element *E = method_list.front(); E; E = E->next()) { + if (E->get().name == "" || (E->get().name[0] == '_' && !(E->get().flags & METHOD_FLAG_VIRTUAL))) { + continue; //hidden, don't count + } + + if (skip_setter_getter_methods && setters_getters.has(E->get().name)) { + // Don't skip parametric setters and getters, i.e. method which require + // one or more parameters to define what property should be set or retrieved. + // E.g. CPUParticles3D::set_param(Parameter param, float value). + if (E->get().arguments.size() == 0 /* getter */ || (E->get().arguments.size() == 1 && E->get().return_val.type == Variant::NIL /* setter */)) { + continue; + } + } + + DocData::MethodDoc method; + + method.name = E->get().name; + + if (E->get().flags & METHOD_FLAG_VIRTUAL) { + method.qualifiers = "virtual"; + } + + if (E->get().flags & METHOD_FLAG_CONST) { + if (method.qualifiers != "") { + method.qualifiers += " "; + } + method.qualifiers += "const"; + } else if (E->get().flags & METHOD_FLAG_VARARG) { + if (method.qualifiers != "") { + method.qualifiers += " "; + } + method.qualifiers += "vararg"; + } + + for (int i = -1; i < E->get().arguments.size(); i++) { + if (i == -1) { +#ifdef DEBUG_METHODS_ENABLED + DocData::return_doc_from_retinfo(method, E->get().return_val); +#endif + } else { + const PropertyInfo &arginfo = E->get().arguments[i]; + DocData::ArgumentDoc argument; + DocData::argument_doc_from_arginfo(argument, arginfo); + + int darg_idx = i - (E->get().arguments.size() - E->get().default_arguments.size()); + if (darg_idx >= 0) { + Variant default_arg = E->get().default_arguments[darg_idx]; + argument.default_value = default_arg.get_construct_string(); + } + + method.arguments.push_back(argument); + } + } + + c.methods.push_back(method); + } + + List signal_list; + ClassDB::get_signal_list(name, &signal_list, true); + + if (signal_list.size()) { + for (List::Element *EV = signal_list.front(); EV; EV = EV->next()) { + DocData::MethodDoc signal; + signal.name = EV->get().name; + for (int i = 0; i < EV->get().arguments.size(); i++) { + const PropertyInfo &arginfo = EV->get().arguments[i]; + DocData::ArgumentDoc argument; + DocData::argument_doc_from_arginfo(argument, arginfo); + + signal.arguments.push_back(argument); + } + + c.signals.push_back(signal); + } + } + + List constant_list; + ClassDB::get_integer_constant_list(name, &constant_list, true); + + for (List::Element *E = constant_list.front(); E; E = E->next()) { + DocData::ConstantDoc constant; + constant.name = E->get(); + constant.value = itos(ClassDB::get_integer_constant(name, E->get())); + constant.is_value_valid = true; + constant.enumeration = ClassDB::get_integer_constant_enum(name, E->get()); + c.constants.push_back(constant); + } + + //theme stuff + + { + List l; + Theme::get_default()->get_constant_list(cname, &l); + for (List::Element *E = l.front(); E; E = E->next()) { + DocData::PropertyDoc pd; + pd.name = E->get(); + pd.type = "int"; + pd.default_value = itos(Theme::get_default()->get_constant(E->get(), cname)); + c.theme_properties.push_back(pd); + } + + l.clear(); + Theme::get_default()->get_color_list(cname, &l); + for (List::Element *E = l.front(); E; E = E->next()) { + DocData::PropertyDoc pd; + pd.name = E->get(); + pd.type = "Color"; + pd.default_value = Variant(Theme::get_default()->get_color(E->get(), cname)).get_construct_string(); + c.theme_properties.push_back(pd); + } + + l.clear(); + Theme::get_default()->get_icon_list(cname, &l); + for (List::Element *E = l.front(); E; E = E->next()) { + DocData::PropertyDoc pd; + pd.name = E->get(); + pd.type = "Texture2D"; + c.theme_properties.push_back(pd); + } + l.clear(); + Theme::get_default()->get_font_list(cname, &l); + for (List::Element *E = l.front(); E; E = E->next()) { + DocData::PropertyDoc pd; + pd.name = E->get(); + pd.type = "Font"; + c.theme_properties.push_back(pd); + } + l.clear(); + Theme::get_default()->get_font_size_list(cname, &l); + for (List::Element *E = l.front(); E; E = E->next()) { + DocData::PropertyDoc pd; + pd.name = E->get(); + pd.type = "int"; + c.theme_properties.push_back(pd); + } + l.clear(); + Theme::get_default()->get_stylebox_list(cname, &l); + for (List::Element *E = l.front(); E; E = E->next()) { + DocData::PropertyDoc pd; + pd.name = E->get(); + pd.type = "StyleBox"; + c.theme_properties.push_back(pd); + } + } + + classes.pop_front(); + } + + { + // So we can document the concept of Variant even if it's not a usable class per se. + class_list["Variant"] = DocData::ClassDoc(); + class_list["Variant"].name = "Variant"; + } + + if (!p_basic_types) { + return; + } + + // Add Variant types. + for (int i = 0; i < Variant::VARIANT_MAX; i++) { + if (i == Variant::NIL) { + continue; // Not exposed outside of 'null', should not be in class list. + } + if (i == Variant::OBJECT) { + continue; // Use the core type instead. + } + + String cname = Variant::get_type_name(Variant::Type(i)); + + class_list[cname] = DocData::ClassDoc(); + DocData::ClassDoc &c = class_list[cname]; + c.name = cname; + + Callable::CallError cerror; + Variant v; + Variant::construct(Variant::Type(i), v, nullptr, 0, cerror); + + List method_list; + v.get_method_list(&method_list); + method_list.sort(); + Variant::get_constructor_list(Variant::Type(i), &method_list); + + for (int j = 0; j < Variant::OP_AND; j++) { // Showing above 'and' is pretty confusing and there are a lot of variations. + for (int k = 0; k < Variant::VARIANT_MAX; k++) { + Variant::Type rt = Variant::get_operator_return_type(Variant::Operator(j), Variant::Type(i), Variant::Type(k)); + if (rt != Variant::NIL) { // Has operator. + // Skip String % operator as it's registered separately for each Variant arg type, + // we'll add it manually below. + if (i == Variant::STRING && Variant::Operator(j) == Variant::OP_MODULE) { + continue; + } + MethodInfo mi; + mi.name = "operator " + Variant::get_operator_name(Variant::Operator(j)); + mi.return_val.type = rt; + if (k != Variant::NIL) { + PropertyInfo arg; + arg.name = "right"; + arg.type = Variant::Type(k); + mi.arguments.push_back(arg); + } + method_list.push_back(mi); + } + } + } + + if (i == Variant::STRING) { + // We skipped % operator above, and we register it manually once for Variant arg type here. + MethodInfo mi; + mi.name = "operator %"; + mi.return_val.type = Variant::STRING; + + PropertyInfo arg; + arg.name = "right"; + arg.type = Variant::NIL; + arg.usage = PROPERTY_USAGE_NIL_IS_VARIANT; + mi.arguments.push_back(arg); + + method_list.push_back(mi); + } + + if (Variant::is_keyed(Variant::Type(i))) { + MethodInfo mi; + mi.name = "operator []"; + mi.return_val.type = Variant::NIL; + mi.return_val.usage = PROPERTY_USAGE_NIL_IS_VARIANT; + + PropertyInfo arg; + arg.name = "key"; + arg.type = Variant::NIL; + arg.usage = PROPERTY_USAGE_NIL_IS_VARIANT; + mi.arguments.push_back(arg); + + method_list.push_back(mi); + } else if (Variant::has_indexing(Variant::Type(i))) { + MethodInfo mi; + mi.name = "operator []"; + mi.return_val.type = Variant::get_indexed_element_type(Variant::Type(i)); + PropertyInfo arg; + arg.name = "index"; + arg.type = Variant::INT; + mi.arguments.push_back(arg); + + method_list.push_back(mi); + } + + for (List::Element *E = method_list.front(); E; E = E->next()) { + MethodInfo &mi = E->get(); + DocData::MethodDoc method; + + method.name = mi.name; + if (method.name == cname) { + method.qualifiers = "constructor"; + } else if (method.name.begins_with("operator")) { + method.qualifiers = "operator"; + } + + for (int j = 0; j < mi.arguments.size(); j++) { + PropertyInfo arginfo = mi.arguments[j]; + DocData::ArgumentDoc ad; + DocData::argument_doc_from_arginfo(ad, mi.arguments[j]); + ad.name = arginfo.name; + + int darg_idx = mi.default_arguments.size() - mi.arguments.size() + j; + if (darg_idx >= 0) { + Variant default_arg = mi.default_arguments[darg_idx]; + ad.default_value = default_arg.get_construct_string(); + } + + method.arguments.push_back(ad); + } + + DocData::return_doc_from_retinfo(method, mi.return_val); + + if (mi.flags & METHOD_FLAG_VARARG) { + if (method.qualifiers != "") { + method.qualifiers += " "; + } + method.qualifiers += "vararg"; + } + + c.methods.push_back(method); + } + + List properties; + v.get_property_list(&properties); + for (List::Element *E = properties.front(); E; E = E->next()) { + PropertyInfo pi = E->get(); + DocData::PropertyDoc property; + property.name = pi.name; + property.type = Variant::get_type_name(pi.type); + property.default_value = v.get(pi.name).get_construct_string(); + + c.properties.push_back(property); + } + + List constants; + Variant::get_constants_for_type(Variant::Type(i), &constants); + + for (List::Element *E = constants.front(); E; E = E->next()) { + DocData::ConstantDoc constant; + constant.name = E->get(); + Variant value = Variant::get_constant_value(Variant::Type(i), E->get()); + constant.value = value.get_type() == Variant::INT ? itos(value) : value.get_construct_string(); + constant.is_value_valid = true; + c.constants.push_back(constant); + } + } + + //built in constants and functions + + { + String cname = "@GlobalScope"; + class_list[cname] = DocData::ClassDoc(); + DocData::ClassDoc &c = class_list[cname]; + c.name = cname; + + for (int i = 0; i < CoreConstants::get_global_constant_count(); i++) { + DocData::ConstantDoc cd; + cd.name = CoreConstants::get_global_constant_name(i); + if (!CoreConstants::get_ignore_value_in_docs(i)) { + cd.value = itos(CoreConstants::get_global_constant_value(i)); + cd.is_value_valid = true; + } else { + cd.is_value_valid = false; + } + cd.enumeration = CoreConstants::get_global_constant_enum(i); + c.constants.push_back(cd); + } + + List singletons; + Engine::get_singleton()->get_singletons(&singletons); + + //servers (this is kind of hackish) + for (List::Element *E = singletons.front(); E; E = E->next()) { + DocData::PropertyDoc pd; + Engine::Singleton &s = E->get(); + if (!s.ptr) { + continue; + } + pd.name = s.name; + pd.type = s.ptr->get_class(); + while (String(ClassDB::get_parent_class(pd.type)) != "Object") { + pd.type = ClassDB::get_parent_class(pd.type); + } + if (pd.type.begins_with("_")) { + pd.type = pd.type.substr(1, pd.type.length()); + } + c.properties.push_back(pd); + } + + List utility_functions; + Variant::get_utility_function_list(&utility_functions); + utility_functions.sort_custom(); + for (List::Element *E = utility_functions.front(); E; E = E->next()) { + DocData::MethodDoc md; + md.name = E->get(); + //return + if (Variant::has_utility_function_return_value(E->get())) { + PropertyInfo pi; + pi.type = Variant::get_utility_function_return_type(E->get()); + if (pi.type == Variant::NIL) { + pi.usage = PROPERTY_USAGE_NIL_IS_VARIANT; + } + DocData::ArgumentDoc ad; + DocData::argument_doc_from_arginfo(ad, pi); + md.return_type = ad.type; + } + + if (Variant::is_utility_function_vararg(E->get())) { + md.qualifiers = "vararg"; + } else { + for (int i = 0; i < Variant::get_utility_function_argument_count(E->get()); i++) { + PropertyInfo pi; + pi.type = Variant::get_utility_function_argument_type(E->get(), i); + pi.name = Variant::get_utility_function_argument_name(E->get(), i); + if (pi.type == Variant::NIL) { + pi.usage = PROPERTY_USAGE_NIL_IS_VARIANT; + } + DocData::ArgumentDoc ad; + DocData::argument_doc_from_arginfo(ad, pi); + md.arguments.push_back(ad); + } + } + + c.methods.push_back(md); + } + } + + // Built-in script reference. + // We only add a doc entry for languages which actually define any built-in + // methods or constants. + + { + for (int i = 0; i < ScriptServer::get_language_count(); i++) { + ScriptLanguage *lang = ScriptServer::get_language(i); + String cname = "@" + lang->get_name(); + DocData::ClassDoc c; + c.name = cname; + + // Get functions. + List minfo; + lang->get_public_functions(&minfo); + + for (List::Element *E = minfo.front(); E; E = E->next()) { + MethodInfo &mi = E->get(); + DocData::MethodDoc md; + md.name = mi.name; + + if (mi.flags & METHOD_FLAG_VARARG) { + if (md.qualifiers != "") { + md.qualifiers += " "; + } + md.qualifiers += "vararg"; + } + + DocData::return_doc_from_retinfo(md, mi.return_val); + + for (int j = 0; j < mi.arguments.size(); j++) { + DocData::ArgumentDoc ad; + DocData::argument_doc_from_arginfo(ad, mi.arguments[j]); + + int darg_idx = j - (mi.arguments.size() - mi.default_arguments.size()); + if (darg_idx >= 0) { + Variant default_arg = E->get().default_arguments[darg_idx]; + ad.default_value = default_arg.get_construct_string(); + } + + md.arguments.push_back(ad); + } + + c.methods.push_back(md); + } + + // Get constants. + List> cinfo; + lang->get_public_constants(&cinfo); + + for (List>::Element *E = cinfo.front(); E; E = E->next()) { + DocData::ConstantDoc cd; + cd.name = E->get().first; + cd.value = E->get().second; + cd.is_value_valid = true; + c.constants.push_back(cd); + } + + // Skip adding the lang if it doesn't expose anything (e.g. C#). + if (c.methods.empty() && c.constants.empty()) { + continue; + } + + class_list[cname] = c; + } + } +} + +static Error _parse_methods(Ref &parser, Vector &methods) { + String section = parser->get_node_name(); + String element = section.substr(0, section.length() - 1); + + while (parser->read() == OK) { + if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { + if (parser->get_node_name() == element) { + DocData::MethodDoc method; + ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); + method.name = parser->get_attribute_value("name"); + if (parser->has_attribute("qualifiers")) { + method.qualifiers = parser->get_attribute_value("qualifiers"); + } + + while (parser->read() == OK) { + if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { + String name = parser->get_node_name(); + if (name == "return") { + ERR_FAIL_COND_V(!parser->has_attribute("type"), ERR_FILE_CORRUPT); + method.return_type = parser->get_attribute_value("type"); + if (parser->has_attribute("enum")) { + method.return_enum = parser->get_attribute_value("enum"); + } + } else if (name == "argument") { + DocData::ArgumentDoc argument; + ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); + argument.name = parser->get_attribute_value("name"); + ERR_FAIL_COND_V(!parser->has_attribute("type"), ERR_FILE_CORRUPT); + argument.type = parser->get_attribute_value("type"); + if (parser->has_attribute("enum")) { + argument.enumeration = parser->get_attribute_value("enum"); + } + + method.arguments.push_back(argument); + + } else if (name == "description") { + parser->read(); + if (parser->get_node_type() == XMLParser::NODE_TEXT) { + method.description = parser->get_node_data(); + } + } + + } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == element) { + break; + } + } + + methods.push_back(method); + + } else { + ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + parser->get_node_name() + "."); + } + + } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == section) { + break; + } + } + + return OK; +} + +Error DocTools::load_classes(const String &p_dir) { + Error err; + DirAccessRef da = DirAccess::open(p_dir, &err); + if (!da) { + return err; + } + + da->list_dir_begin(); + String path; + path = da->get_next(); + while (path != String()) { + if (!da->current_is_dir() && path.ends_with("xml")) { + Ref parser = memnew(XMLParser); + Error err2 = parser->open(p_dir.plus_file(path)); + if (err2) { + return err2; + } + + _load(parser); + } + path = da->get_next(); + } + + da->list_dir_end(); + + return OK; +} + +Error DocTools::erase_classes(const String &p_dir) { + Error err; + DirAccessRef da = DirAccess::open(p_dir, &err); + if (!da) { + return err; + } + + List to_erase; + + da->list_dir_begin(); + String path; + path = da->get_next(); + while (path != String()) { + if (!da->current_is_dir() && path.ends_with("xml")) { + to_erase.push_back(path); + } + path = da->get_next(); + } + da->list_dir_end(); + + while (to_erase.size()) { + da->remove(to_erase.front()->get()); + to_erase.pop_front(); + } + + return OK; +} + +Error DocTools::_load(Ref parser) { + Error err = OK; + + while ((err = parser->read()) == OK) { + if (parser->get_node_type() == XMLParser::NODE_ELEMENT && parser->get_node_name() == "?xml") { + parser->skip_section(); + } + + if (parser->get_node_type() != XMLParser::NODE_ELEMENT) { + continue; //no idea what this may be, but skipping anyway + } + + ERR_FAIL_COND_V(parser->get_node_name() != "class", ERR_FILE_CORRUPT); + + ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); + String name = parser->get_attribute_value("name"); + class_list[name] = DocData::ClassDoc(); + DocData::ClassDoc &c = class_list[name]; + + c.name = name; + if (parser->has_attribute("inherits")) { + c.inherits = parser->get_attribute_value("inherits"); + } + + while (parser->read() == OK) { + if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { + String name2 = parser->get_node_name(); + + if (name2 == "brief_description") { + parser->read(); + if (parser->get_node_type() == XMLParser::NODE_TEXT) { + c.brief_description = parser->get_node_data(); + } + + } else if (name2 == "description") { + parser->read(); + if (parser->get_node_type() == XMLParser::NODE_TEXT) { + c.description = parser->get_node_data(); + } + } else if (name2 == "tutorials") { + while (parser->read() == OK) { + if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { + String name3 = parser->get_node_name(); + + if (name3 == "link") { + DocData::TutorialDoc tutorial; + if (parser->has_attribute("title")) { + tutorial.title = parser->get_attribute_value("title"); + } + parser->read(); + if (parser->get_node_type() == XMLParser::NODE_TEXT) { + tutorial.link = parser->get_node_data().strip_edges(); + c.tutorials.push_back(tutorial); + } + } else { + ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + name3 + "."); + } + } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == "tutorials") { + break; // End of . + } + } + } else if (name2 == "methods") { + Error err2 = _parse_methods(parser, c.methods); + ERR_FAIL_COND_V(err2, err2); + + } else if (name2 == "signals") { + Error err2 = _parse_methods(parser, c.signals); + ERR_FAIL_COND_V(err2, err2); + } else if (name2 == "members") { + while (parser->read() == OK) { + if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { + String name3 = parser->get_node_name(); + + if (name3 == "member") { + DocData::PropertyDoc prop2; + + ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); + prop2.name = parser->get_attribute_value("name"); + ERR_FAIL_COND_V(!parser->has_attribute("type"), ERR_FILE_CORRUPT); + prop2.type = parser->get_attribute_value("type"); + if (parser->has_attribute("setter")) { + prop2.setter = parser->get_attribute_value("setter"); + } + if (parser->has_attribute("getter")) { + prop2.getter = parser->get_attribute_value("getter"); + } + if (parser->has_attribute("enum")) { + prop2.enumeration = parser->get_attribute_value("enum"); + } + if (!parser->is_empty()) { + parser->read(); + if (parser->get_node_type() == XMLParser::NODE_TEXT) { + prop2.description = parser->get_node_data(); + } + } + c.properties.push_back(prop2); + } else { + ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + name3 + "."); + } + + } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == "members") { + break; // End of . + } + } + + } else if (name2 == "theme_items") { + while (parser->read() == OK) { + if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { + String name3 = parser->get_node_name(); + + if (name3 == "theme_item") { + DocData::PropertyDoc prop2; + + ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); + prop2.name = parser->get_attribute_value("name"); + ERR_FAIL_COND_V(!parser->has_attribute("type"), ERR_FILE_CORRUPT); + prop2.type = parser->get_attribute_value("type"); + if (!parser->is_empty()) { + parser->read(); + if (parser->get_node_type() == XMLParser::NODE_TEXT) { + prop2.description = parser->get_node_data(); + } + } + c.theme_properties.push_back(prop2); + } else { + ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + name3 + "."); + } + + } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == "theme_items") { + break; // End of . + } + } + + } else if (name2 == "constants") { + while (parser->read() == OK) { + if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { + String name3 = parser->get_node_name(); + + if (name3 == "constant") { + DocData::ConstantDoc constant2; + ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT); + constant2.name = parser->get_attribute_value("name"); + ERR_FAIL_COND_V(!parser->has_attribute("value"), ERR_FILE_CORRUPT); + constant2.value = parser->get_attribute_value("value"); + constant2.is_value_valid = true; + if (parser->has_attribute("enum")) { + constant2.enumeration = parser->get_attribute_value("enum"); + } + if (!parser->is_empty()) { + parser->read(); + if (parser->get_node_type() == XMLParser::NODE_TEXT) { + constant2.description = parser->get_node_data(); + } + } + c.constants.push_back(constant2); + } else { + ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + name3 + "."); + } + + } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == "constants") { + break; // End of . + } + } + + } else { + ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + name2 + "."); + } + + } else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == "class") { + break; // End of . + } + } + } + + return OK; +} + +static void _write_string(FileAccess *f, int p_tablevel, const String &p_string) { + if (p_string == "") { + return; + } + String tab; + for (int i = 0; i < p_tablevel; i++) { + tab += "\t"; + } + f->store_string(tab + p_string + "\n"); +} + +Error DocTools::save_classes(const String &p_default_path, const Map &p_class_path) { + for (Map::Element *E = class_list.front(); E; E = E->next()) { + DocData::ClassDoc &c = E->get(); + + String save_path; + if (p_class_path.has(c.name)) { + save_path = p_class_path[c.name]; + } else { + save_path = p_default_path; + } + + Error err; + String save_file = save_path.plus_file(c.name + ".xml"); + FileAccessRef f = FileAccess::open(save_file, FileAccess::WRITE, &err); + + ERR_CONTINUE_MSG(err != OK, "Can't write doc file: " + save_file + "."); + + _write_string(f, 0, ""); + + String header = ""); + _write_string(f, 2, c.brief_description.strip_edges().xml_escape()); + _write_string(f, 1, ""); + + _write_string(f, 1, ""); + _write_string(f, 2, c.description.strip_edges().xml_escape()); + _write_string(f, 1, ""); + + _write_string(f, 1, ""); + for (int i = 0; i < c.tutorials.size(); i++) { + DocData::TutorialDoc tutorial = c.tutorials.get(i); + String title_attribute = (!tutorial.title.empty()) ? " title=\"" + tutorial.title.xml_escape() + "\"" : ""; + _write_string(f, 2, "" + tutorial.link.xml_escape() + ""); + } + _write_string(f, 1, ""); + + _write_string(f, 1, ""); + + c.methods.sort(); + + for (int i = 0; i < c.methods.size(); i++) { + const DocData::MethodDoc &m = c.methods[i]; + + String qualifiers; + if (m.qualifiers != "") { + qualifiers += " qualifiers=\"" + m.qualifiers.xml_escape() + "\""; + } + + _write_string(f, 2, ""); + + if (m.return_type != "") { + String enum_text; + if (m.return_enum != String()) { + enum_text = " enum=\"" + m.return_enum + "\""; + } + _write_string(f, 3, ""); + _write_string(f, 3, ""); + } + + for (int j = 0; j < m.arguments.size(); j++) { + const DocData::ArgumentDoc &a = m.arguments[j]; + + String enum_text; + if (a.enumeration != String()) { + enum_text = " enum=\"" + a.enumeration + "\""; + } + + if (a.default_value != "") { + _write_string(f, 3, ""); + } else { + _write_string(f, 3, ""); + } + + _write_string(f, 3, ""); + } + + _write_string(f, 3, ""); + _write_string(f, 4, m.description.strip_edges().xml_escape()); + _write_string(f, 3, ""); + + _write_string(f, 2, ""); + } + + _write_string(f, 1, ""); + + if (c.properties.size()) { + _write_string(f, 1, ""); + + c.properties.sort(); + + for (int i = 0; i < c.properties.size(); i++) { + String additional_attributes; + if (c.properties[i].enumeration != String()) { + additional_attributes += " enum=\"" + c.properties[i].enumeration + "\""; + } + if (c.properties[i].default_value != String()) { + additional_attributes += " default=\"" + c.properties[i].default_value.xml_escape(true) + "\""; + } + + const DocData::PropertyDoc &p = c.properties[i]; + + if (c.properties[i].overridden) { + _write_string(f, 2, ""); + } else { + _write_string(f, 2, ""); + _write_string(f, 3, p.description.strip_edges().xml_escape()); + _write_string(f, 2, ""); + } + } + _write_string(f, 1, ""); + } + + if (c.signals.size()) { + c.signals.sort(); + + _write_string(f, 1, ""); + for (int i = 0; i < c.signals.size(); i++) { + const DocData::MethodDoc &m = c.signals[i]; + _write_string(f, 2, ""); + for (int j = 0; j < m.arguments.size(); j++) { + const DocData::ArgumentDoc &a = m.arguments[j]; + _write_string(f, 3, ""); + _write_string(f, 3, ""); + } + + _write_string(f, 3, ""); + _write_string(f, 4, m.description.strip_edges().xml_escape()); + _write_string(f, 3, ""); + + _write_string(f, 2, ""); + } + + _write_string(f, 1, ""); + } + + _write_string(f, 1, ""); + + for (int i = 0; i < c.constants.size(); i++) { + const DocData::ConstantDoc &k = c.constants[i]; + if (k.is_value_valid) { + if (k.enumeration != String()) { + _write_string(f, 2, ""); + } else { + _write_string(f, 2, ""); + } + } else { + if (k.enumeration != String()) { + _write_string(f, 2, ""); + } else { + _write_string(f, 2, ""); + } + } + _write_string(f, 3, k.description.strip_edges().xml_escape()); + _write_string(f, 2, ""); + } + + _write_string(f, 1, ""); + + if (c.theme_properties.size()) { + c.theme_properties.sort(); + + _write_string(f, 1, ""); + for (int i = 0; i < c.theme_properties.size(); i++) { + const DocData::PropertyDoc &p = c.theme_properties[i]; + + if (p.default_value != "") { + _write_string(f, 2, ""); + } else { + _write_string(f, 2, ""); + } + + _write_string(f, 3, p.description.strip_edges().xml_escape()); + + _write_string(f, 2, ""); + } + _write_string(f, 1, ""); + } + + _write_string(f, 0, ""); + } + + return OK; +} + +Error DocTools::load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size) { + Vector data; + data.resize(p_uncompressed_size); + Compression::decompress(data.ptrw(), p_uncompressed_size, p_data, p_compressed_size, Compression::MODE_DEFLATE); + class_list.clear(); + + Ref parser = memnew(XMLParser); + Error err = parser->open_buffer(data); + if (err) { + return err; + } + + _load(parser); + + return OK; +} diff --git a/editor/doc_tools.h b/editor/doc_tools.h new file mode 100644 index 0000000000..db27e38c8b --- /dev/null +++ b/editor/doc_tools.h @@ -0,0 +1,56 @@ +/*************************************************************************/ +/* doc_tools.h */ +/*************************************************************************/ +/* This file is part of: */ +/* GODOT ENGINE */ +/* https://godotengine.org */ +/*************************************************************************/ +/* Copyright (c) 2007-2020 Juan Linietsky, Ariel Manzur. */ +/* Copyright (c) 2014-2020 Godot Engine contributors (cf. AUTHORS.md). */ +/* */ +/* 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. */ +/*************************************************************************/ + +#ifndef DOC_TOOLS_H +#define DOC_TOOLS_H + +#include "core/doc_data.h" + +class DocTools { +public: + String version; + Map class_list; + + static Error erase_classes(const String &p_dir); + + void merge_from(const DocTools &p_data); + void remove_from(const DocTools &p_data); + void add_doc(const DocData::ClassDoc &p_class_doc); + void remove_doc(const String &p_class_name); + bool has_doc(const String &p_class_name); + void generate(bool p_basic_types = false); + Error load_classes(const String &p_dir); + Error save_classes(const String &p_default_path, const Map &p_class_path); + + Error _load(Ref parser); + Error load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size); +}; + +#endif // DOC_DATA_H diff --git a/editor/editor_file_system.cpp b/editor/editor_file_system.cpp index 44c29ab81f..6dcc505a11 100644 --- a/editor/editor_file_system.cpp +++ b/editor/editor_file_system.cpp @@ -799,11 +799,16 @@ void EditorFileSystem::_scan_new_dir(EditorFileSystemDirectory *p_dir, DirAccess } } - if (fc) { - for (int i = 0; i < ScriptServer::get_language_count(); i++) { - ScriptLanguage *lang = ScriptServer::get_language(i); - if (lang->has_documentation() && fc->type == lang->get_type()) { - ResourceLoader::load(path); + for (int i = 0; i < ScriptServer::get_language_count(); i++) { + ScriptLanguage *lang = ScriptServer::get_language(i); + if (lang->supports_documentation() && fi->type == lang->get_type()) { + Ref