From cc4bda85008a6c2bd78d86bab6e836b3d3273e03 Mon Sep 17 00:00:00 2001 From: SaracenOne Date: Sun, 28 Aug 2022 07:17:25 +0100 Subject: [PATCH] Add ability to flag classes as experimental or deprecated. --- core/doc_data.h | 8 +++ editor/create_dialog.cpp | 9 ++++ editor/doc_tools.cpp | 88 +++++++++++++++++++++++++++++--- editor/editor_help.cpp | 94 +++++++++++++++++++++++++++++++++++ editor/editor_help_search.cpp | 30 ++++++++--- editor/editor_help_search.h | 2 +- scene/main/node.h | 4 ++ 7 files changed, 221 insertions(+), 14 deletions(-) diff --git a/core/doc_data.h b/core/doc_data.h index 1d8d2483e0f..3b7bf149b4f 100644 --- a/core/doc_data.h +++ b/core/doc_data.h @@ -66,6 +66,8 @@ public: String return_enum; String qualifiers; String description; + bool is_deprecated = false; + bool is_experimental = false; Vector arguments; Vector errors_returned; bool operator<(const MethodDoc &p_method) const { @@ -105,6 +107,8 @@ public: String enumeration; bool is_bitfield = false; String description; + bool is_deprecated = false; + bool is_experimental = false; bool operator<(const ConstantDoc &p_const) const { return name < p_const.name; } @@ -126,6 +130,8 @@ public: String default_value; bool overridden = false; String overrides; + bool is_deprecated = false; + bool is_experimental = false; bool operator<(const PropertyDoc &p_prop) const { return name < p_prop.name; } @@ -167,6 +173,8 @@ public: Vector properties; Vector annotations; Vector theme_properties; + bool is_deprecated = false; + bool is_experimental = false; bool is_script_doc = false; String script_path; bool operator<(const ClassDoc &p_class) const { diff --git a/editor/create_dialog.cpp b/editor/create_dialog.cpp index 4ac32d73171..3e72c6211d8 100644 --- a/editor/create_dialog.cpp +++ b/editor/create_dialog.cpp @@ -296,6 +296,15 @@ void CreateDialog::_configure_search_option_item(TreeItem *r_item, const String r_item->set_icon(0, EditorNode::get_singleton()->get_class_icon(p_type, icon_fallback)); } + bool is_deprecated = EditorHelp::get_doc_data()->class_list[p_type].is_deprecated; + bool is_experimental = EditorHelp::get_doc_data()->class_list[p_type].is_experimental; + + if (is_deprecated) { + r_item->add_button(0, get_theme_icon("StatusError", SNAME("EditorIcons")), 0, false, TTR("This class is marked as deprecated.")); + } else if (is_experimental) { + r_item->add_button(0, get_theme_icon("NodeWarning", SNAME("EditorIcons")), 0, false, TTR("This class is marked as experimental.")); + } + if (!search_box->get_text().is_empty()) { r_item->set_collapsed(false); } else { diff --git a/editor/doc_tools.cpp b/editor/doc_tools.cpp index ec9a744e572..9f655ab00ab 100644 --- a/editor/doc_tools.cpp +++ b/editor/doc_tools.cpp @@ -85,6 +85,9 @@ void DocTools::merge_from(const DocTools &p_data) { const DocData::ClassDoc &cf = p_data.class_list[c.name]; + c.is_deprecated = cf.is_deprecated; + c.is_experimental = cf.is_experimental; + c.description = cf.description; c.brief_description = cf.brief_description; c.tutorials = cf.tutorials; @@ -133,6 +136,8 @@ void DocTools::merge_from(const DocTools &p_data) { const DocData::MethodDoc &mf = cf.constructors[j]; m.description = mf.description; + m.is_deprecated = mf.is_deprecated; + m.is_experimental = mf.is_experimental; break; } } @@ -148,6 +153,8 @@ void DocTools::merge_from(const DocTools &p_data) { const DocData::MethodDoc &mf = cf.methods[j]; m.description = mf.description; + m.is_deprecated = mf.is_deprecated; + m.is_experimental = mf.is_experimental; break; } } @@ -162,6 +169,8 @@ void DocTools::merge_from(const DocTools &p_data) { const DocData::MethodDoc &mf = cf.signals[j]; m.description = mf.description; + m.is_deprecated = mf.is_deprecated; + m.is_experimental = mf.is_experimental; break; } } @@ -176,6 +185,8 @@ void DocTools::merge_from(const DocTools &p_data) { const DocData::ConstantDoc &mf = cf.constants[j]; m.description = mf.description; + m.is_deprecated = mf.is_deprecated; + m.is_experimental = mf.is_experimental; break; } } @@ -190,6 +201,8 @@ void DocTools::merge_from(const DocTools &p_data) { const DocData::MethodDoc &mf = cf.annotations[j]; m.description = mf.description; + m.is_deprecated = mf.is_deprecated; + m.is_experimental = mf.is_experimental; break; } } @@ -204,6 +217,8 @@ void DocTools::merge_from(const DocTools &p_data) { const DocData::PropertyDoc &pf = cf.properties[j]; p.description = pf.description; + p.is_deprecated = pf.is_deprecated; + p.is_experimental = pf.is_experimental; break; } } @@ -266,6 +281,8 @@ void DocTools::merge_from(const DocTools &p_data) { const DocData::MethodDoc &mf = cf.operators[j]; m.description = mf.description; + m.is_deprecated = mf.is_deprecated; + m.is_experimental = mf.is_experimental; break; } } @@ -1007,6 +1024,12 @@ static Error _parse_methods(Ref &parser, Vector & if (parser->has_attribute("qualifiers")) { method.qualifiers = parser->get_attribute_value("qualifiers"); } + if (parser->has_attribute("is_deprecated")) { + method.is_deprecated = parser->get_attribute_value("is_deprecated").to_lower() == "true"; + } + if (parser->has_attribute("is_experimental")) { + method.is_experimental = parser->get_attribute_value("is_experimental").to_lower() == "true"; + } while (parser->read() == OK) { if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { @@ -1138,6 +1161,16 @@ Error DocTools::_load(Ref parser) { c.inherits = parser->get_attribute_value("inherits"); } + if (parser->has_attribute("is_deprecated")) { + String result = parser->get_attribute_value("is_deprecated"); + c.is_deprecated = (result == "true" || result == "True" || result == "TRUE" || result == "1"); + } + + if (parser->has_attribute("is_experimental")) { + String result = parser->get_attribute_value("is_experimental"); + c.is_experimental = (result == "true" || result == "True" || result == "TRUE" || result == "1"); + } + while (parser->read() == OK) { if (parser->get_node_type() == XMLParser::NODE_ELEMENT) { String name2 = parser->get_node_name(); @@ -1211,6 +1244,12 @@ Error DocTools::_load(Ref parser) { if (parser->has_attribute("enum")) { prop2.enumeration = parser->get_attribute_value("enum"); } + if (parser->has_attribute("is_deprecated")) { + prop2.is_deprecated = parser->get_attribute_value("is_deprecated").to_lower() == "true"; + } + if (parser->has_attribute("is_experimental")) { + prop2.is_experimental = parser->get_attribute_value("is_experimental").to_lower() == "true"; + } if (!parser->is_empty()) { parser->read(); if (parser->get_node_type() == XMLParser::NODE_TEXT) { @@ -1275,6 +1314,14 @@ Error DocTools::_load(Ref parser) { if (parser->has_attribute("is_bitfield")) { constant2.is_bitfield = parser->get_attribute_value("is_bitfield").to_lower() == "true"; } + if (parser->has_attribute("is_deprecated")) { + String result = parser->get_attribute_value("is_deprecated"); + constant2.is_deprecated = (result == "true" || result == "True" || result == "TRUE" || result == "1"); + } + if (parser->has_attribute("is_experimental")) { + String result = parser->get_attribute_value("is_experimental"); + constant2.is_experimental = (result == "true" || result == "True" || result == "TRUE" || result == "1"); + } if (!parser->is_empty()) { parser->read(); if (parser->get_node_type() == XMLParser::NODE_TEXT) { @@ -1327,7 +1374,15 @@ static void _write_method_doc(Ref f, const String &p_name, Vector"); + String additional_attributes; + if (m.is_deprecated) { + additional_attributes += " is_deprecated=\"True\""; + } + if (m.is_experimental) { + additional_attributes += " is_experimental=\"True\""; + } + + _write_string(f, 2, "<" + p_name + " name=\"" + m.name.xml_escape() + "\"" + qualifiers + additional_attributes + ">"); if (!m.return_type.is_empty()) { String enum_text; @@ -1390,6 +1445,12 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap"); for (int i = 0; i < c.constants.size(); i++) { const DocData::ConstantDoc &k = c.constants[i]; + + String additional_attributes; + if (c.constants[i].is_deprecated) { + additional_attributes += " is_deprecated=\"True\""; + } + if (c.constants[i].is_experimental) { + additional_attributes += " is_experimental=\"True\""; + } + if (k.is_value_valid) { if (!k.enumeration.is_empty()) { if (k.is_bitfield) { - _write_string(f, 2, ""); + _write_string(f, 2, ""); } else { - _write_string(f, 2, ""); + _write_string(f, 2, ""); } } else { - _write_string(f, 2, ""); + _write_string(f, 2, ""); } } else { if (!k.enumeration.is_empty()) { - _write_string(f, 2, ""); + _write_string(f, 2, ""); } else { - _write_string(f, 2, ""); + _write_string(f, 2, ""); } } _write_string(f, 3, _translate_doc_string(k.description).strip_edges().xml_escape()); diff --git a/editor/editor_help.cpp b/editor/editor_help.cpp index b8f115e82e1..745dcdd04c7 100644 --- a/editor/editor_help.cpp +++ b/editor/editor_help.cpp @@ -276,6 +276,23 @@ String EditorHelp::_fix_constant(const String &p_constant) const { return p_constant; } +// Macros for assigning the deprecation/experimental information to class members +#define DEPRECATED_DOC_TAG \ + class_desc->push_color(get_theme_color(SNAME("error_color"), SNAME("Editor"))); \ + Ref error_icon = get_theme_icon(SNAME("StatusError"), SNAME("EditorIcons")); \ + class_desc->add_text(" "); \ + class_desc->add_image(error_icon, error_icon->get_width(), error_icon->get_height()); \ + class_desc->add_text(" (" + TTR("Deprecated") + ")"); \ + class_desc->pop(); + +#define EXPERIMENTAL_DOC_TAG \ + class_desc->push_color(get_theme_color(SNAME("warning_color"), SNAME("Editor"))); \ + Ref warning_icon = get_theme_icon(SNAME("NodeWarning"), SNAME("EditorIcons")); \ + class_desc->add_text(" "); \ + class_desc->add_image(warning_icon, warning_icon->get_width(), warning_icon->get_height()); \ + class_desc->add_text(" (" + TTR("Experimental") + ")"); \ + class_desc->pop(); + void EditorHelp::_add_method(const DocData::MethodDoc &p_method, bool p_overview) { method_line[p_method.name] = class_desc->get_paragraph_count() - 2; //gets overridden if description @@ -356,6 +373,14 @@ void EditorHelp::_add_method(const DocData::MethodDoc &p_method, bool p_overview class_desc->pop(); } + if (p_method.is_deprecated) { + DEPRECATED_DOC_TAG; + } + + if (p_method.is_experimental) { + EXPERIMENTAL_DOC_TAG; + } + if (p_overview) { class_desc->pop(); //cell } @@ -565,6 +590,17 @@ void EditorHelp::_update_doc() { class_desc->pop(); // color class_desc->pop(); // font size class_desc->pop(); // font + + if (cd.is_deprecated) { + class_desc->add_text(" "); + Ref error_icon = get_theme_icon(SNAME("StatusError"), SNAME("EditorIcons")); + class_desc->add_image(error_icon, error_icon->get_width(), error_icon->get_height()); + } + if (cd.is_experimental) { + class_desc->add_text(" "); + Ref warning_icon = get_theme_icon(SNAME("NodeWarning"), SNAME("EditorIcons")); + class_desc->add_image(warning_icon, warning_icon->get_width(), warning_icon->get_height()); + } class_desc->add_newline(); const String non_breaking_space = String::chr(160); @@ -627,6 +663,26 @@ void EditorHelp::_update_doc() { } } + // Note if deprecated. + if (cd.is_deprecated) { + Ref error_icon = get_theme_icon(SNAME("StatusError"), SNAME("EditorIcons")); + class_desc->push_color(get_theme_color(SNAME("error_color"), SNAME("Editor"))); + class_desc->add_image(error_icon, error_icon->get_width(), error_icon->get_height()); + class_desc->add_text(String(" ") + TTR("This class is marked as deprecated. It will be removed in future versions.")); + class_desc->pop(); + class_desc->add_newline(); + } + + // Note if experimental. + if (cd.is_experimental) { + Ref warning_icon = get_theme_icon(SNAME("NodeWarning"), SNAME("EditorIcons")); + class_desc->push_color(get_theme_color(SNAME("warning_color"), SNAME("Editor"))); + class_desc->add_image(warning_icon, warning_icon->get_width(), warning_icon->get_height()); + class_desc->add_text(String(" ") + TTR("This class is marked as experimental. It is subject to likely change or possible removal in future versions. Use at your own discretion.")); + class_desc->pop(); + class_desc->add_newline(); + } + class_desc->add_newline(); class_desc->add_newline(); @@ -817,6 +873,13 @@ void EditorHelp::_update_doc() { class_desc->pop(); } + if (cd.properties[i].is_deprecated) { + DEPRECATED_DOC_TAG; + } + if (cd.properties[i].is_experimental) { + EXPERIMENTAL_DOC_TAG; + } + class_desc->pop(); class_desc->pop(); // cell @@ -1066,6 +1129,14 @@ void EditorHelp::_update_doc() { class_desc->push_color(symbol_color); class_desc->add_text(")"); + + if (cd.signals[i].is_deprecated) { + DEPRECATED_DOC_TAG; + } + if (cd.signals[i].is_experimental) { + EXPERIMENTAL_DOC_TAG; + } + class_desc->pop(); class_desc->pop(); // end monofont if (!cd.signals[i].description.strip_edges().is_empty()) { @@ -1187,6 +1258,14 @@ void EditorHelp::_update_doc() { class_desc->pop(); class_desc->pop(); + if (enum_list[i].is_deprecated) { + DEPRECATED_DOC_TAG; + } + + if (enum_list[i].is_experimental) { + EXPERIMENTAL_DOC_TAG; + } + class_desc->add_newline(); if (!enum_list[i].description.strip_edges().is_empty()) { @@ -1258,6 +1337,14 @@ void EditorHelp::_update_doc() { class_desc->pop(); + if (constants[i].is_deprecated) { + DEPRECATED_DOC_TAG; + } + + if (constants[i].is_experimental) { + EXPERIMENTAL_DOC_TAG; + } + class_desc->add_newline(); if (!constants[i].description.strip_edges().is_empty()) { @@ -1438,6 +1525,13 @@ void EditorHelp::_update_doc() { class_desc->pop(); // color } + if (cd.properties[i].is_deprecated) { + DEPRECATED_DOC_TAG; + } + if (cd.properties[i].is_experimental) { + EXPERIMENTAL_DOC_TAG; + } + if (cd.is_script_doc && (!cd.properties[i].setter.is_empty() || !cd.properties[i].getter.is_empty())) { class_desc->push_color(symbol_color); class_desc->add_text(" [" + TTR("property:") + " "); diff --git a/editor/editor_help_search.cpp b/editor/editor_help_search.cpp index af0cff9ad6e..129ad4d33bd 100644 --- a/editor/editor_help_search.cpp +++ b/editor/editor_help_search.cpp @@ -599,6 +599,14 @@ TreeItem *EditorHelpSearch::Runner::_create_class_item(TreeItem *p_parent, const item->set_custom_color(1, disabled_color); } + if (p_doc->is_deprecated) { + Ref error_icon = ui_service->get_theme_icon("StatusError", SNAME("EditorIcons")); + item->add_button(0, error_icon, 0, false, TTR("This class is marked as deprecated.")); + } else if (p_doc->is_experimental) { + Ref warning_icon = ui_service->get_theme_icon("NodeWarning", SNAME("EditorIcons")); + item->add_button(0, warning_icon, 0, false, TTR("This class is marked as experimental.")); + } + _match_item(item, p_doc->name); return item; @@ -606,37 +614,37 @@ TreeItem *EditorHelpSearch::Runner::_create_class_item(TreeItem *p_parent, const TreeItem *EditorHelpSearch::Runner::_create_method_item(TreeItem *p_parent, const DocData::ClassDoc *p_class_doc, const String &p_text, const DocData::MethodDoc *p_doc) { String tooltip = _build_method_tooltip(p_class_doc, p_doc); - return _create_member_item(p_parent, p_class_doc->name, "MemberMethod", p_doc->name, p_text, TTRC("Method"), "method", tooltip); + return _create_member_item(p_parent, p_class_doc->name, "MemberMethod", p_doc->name, p_text, TTRC("Method"), "method", tooltip, p_doc->is_deprecated, p_doc->is_experimental); } TreeItem *EditorHelpSearch::Runner::_create_signal_item(TreeItem *p_parent, const DocData::ClassDoc *p_class_doc, const DocData::MethodDoc *p_doc) { String tooltip = _build_method_tooltip(p_class_doc, p_doc); - return _create_member_item(p_parent, p_class_doc->name, "MemberSignal", p_doc->name, p_doc->name, TTRC("Signal"), "signal", tooltip); + return _create_member_item(p_parent, p_class_doc->name, "MemberSignal", p_doc->name, p_doc->name, TTRC("Signal"), "signal", tooltip, p_doc->is_deprecated, p_doc->is_experimental); } TreeItem *EditorHelpSearch::Runner::_create_annotation_item(TreeItem *p_parent, const DocData::ClassDoc *p_class_doc, const String &p_text, const DocData::MethodDoc *p_doc) { String tooltip = _build_method_tooltip(p_class_doc, p_doc); - return _create_member_item(p_parent, p_class_doc->name, "MemberAnnotation", p_doc->name, p_text, TTRC("Annotation"), "annotation", tooltip); + return _create_member_item(p_parent, p_class_doc->name, "MemberAnnotation", p_doc->name, p_text, TTRC("Annotation"), "annotation", tooltip, p_doc->is_deprecated, p_doc->is_experimental); } TreeItem *EditorHelpSearch::Runner::_create_constant_item(TreeItem *p_parent, const DocData::ClassDoc *p_class_doc, const DocData::ConstantDoc *p_doc) { String tooltip = p_class_doc->name + "." + p_doc->name; - return _create_member_item(p_parent, p_class_doc->name, "MemberConstant", p_doc->name, p_doc->name, TTRC("Constant"), "constant", tooltip); + return _create_member_item(p_parent, p_class_doc->name, "MemberConstant", p_doc->name, p_doc->name, TTRC("Constant"), "constant", tooltip, p_doc->is_deprecated, p_doc->is_experimental); } TreeItem *EditorHelpSearch::Runner::_create_property_item(TreeItem *p_parent, const DocData::ClassDoc *p_class_doc, const DocData::PropertyDoc *p_doc) { String tooltip = p_doc->type + " " + p_class_doc->name + "." + p_doc->name; tooltip += "\n " + p_class_doc->name + "." + p_doc->setter + "(value) setter"; tooltip += "\n " + p_class_doc->name + "." + p_doc->getter + "() getter"; - return _create_member_item(p_parent, p_class_doc->name, "MemberProperty", p_doc->name, p_doc->name, TTRC("Property"), "property", tooltip); + return _create_member_item(p_parent, p_class_doc->name, "MemberProperty", p_doc->name, p_doc->name, TTRC("Property"), "property", tooltip, p_doc->is_deprecated, p_doc->is_experimental); } TreeItem *EditorHelpSearch::Runner::_create_theme_property_item(TreeItem *p_parent, const DocData::ClassDoc *p_class_doc, const DocData::ThemeItemDoc *p_doc) { String tooltip = p_doc->type + " " + p_class_doc->name + "." + p_doc->name; - return _create_member_item(p_parent, p_class_doc->name, "MemberTheme", p_doc->name, p_doc->name, TTRC("Theme Property"), "theme_item", tooltip); + return _create_member_item(p_parent, p_class_doc->name, "MemberTheme", p_doc->name, p_doc->name, TTRC("Theme Property"), "theme_item", tooltip, false, false); } -TreeItem *EditorHelpSearch::Runner::_create_member_item(TreeItem *p_parent, const String &p_class_name, const String &p_icon, const String &p_name, const String &p_text, const String &p_type, const String &p_metatype, const String &p_tooltip) { +TreeItem *EditorHelpSearch::Runner::_create_member_item(TreeItem *p_parent, const String &p_class_name, const String &p_icon, const String &p_name, const String &p_text, const String &p_type, const String &p_metatype, const String &p_tooltip, bool is_deprecated, bool is_experimental) { Ref icon; String text; if (search_flags & SEARCH_SHOW_HIERARCHY) { @@ -655,6 +663,14 @@ TreeItem *EditorHelpSearch::Runner::_create_member_item(TreeItem *p_parent, cons item->set_tooltip_text(1, p_tooltip); item->set_metadata(0, "class_" + p_metatype + ":" + p_class_name + ":" + p_name); + if (is_deprecated) { + Ref error_icon = ui_service->get_theme_icon("StatusError", SNAME("EditorIcons")); + item->add_button(0, error_icon, 0, false, TTR("This member is marked as deprecated.")); + } else if (is_experimental) { + Ref warning_icon = ui_service->get_theme_icon("NodeWarning", SNAME("EditorIcons")); + item->add_button(0, warning_icon, 0, false, TTR("This member is marked as experimental.")); + } + _match_item(item, p_name); return item; diff --git a/editor/editor_help_search.h b/editor/editor_help_search.h index 26abaec6e69..efd8645cd7e 100644 --- a/editor/editor_help_search.h +++ b/editor/editor_help_search.h @@ -155,7 +155,7 @@ class EditorHelpSearch::Runner : public RefCounted { TreeItem *_create_constant_item(TreeItem *p_parent, const DocData::ClassDoc *p_class_doc, const DocData::ConstantDoc *p_doc); TreeItem *_create_property_item(TreeItem *p_parent, const DocData::ClassDoc *p_class_doc, const DocData::PropertyDoc *p_doc); TreeItem *_create_theme_property_item(TreeItem *p_parent, const DocData::ClassDoc *p_class_doc, const DocData::ThemeItemDoc *p_doc); - TreeItem *_create_member_item(TreeItem *p_parent, const String &p_class_name, const String &p_icon, const String &p_name, const String &p_text, const String &p_type, const String &p_metatype, const String &p_tooltip); + TreeItem *_create_member_item(TreeItem *p_parent, const String &p_class_name, const String &p_icon, const String &p_name, const String &p_text, const String &p_type, const String &p_metatype, const String &p_tooltip, bool is_deprecated, bool is_experimental); public: bool work(uint64_t slot = 100000); diff --git a/scene/main/node.h b/scene/main/node.h index 39225b1358e..13a938ef97d 100644 --- a/scene/main/node.h +++ b/scene/main/node.h @@ -529,4 +529,8 @@ Error Node::rpc_id(int p_peer_id, const StringName &p_method, VarArgs... p_args) return rpcp(p_peer_id, p_method, sizeof...(p_args) == 0 ? nullptr : (const Variant **)argptrs, sizeof...(p_args)); } +// Add these macro to your class's 'get_configuration_warnings' function to have warnings show up in the scene tree inspector. +#define DEPRECATED_NODE_WARNING warnings.push_back(RTR("This node is marked as deprecated and will be removed in future versions.\nPlease check the Godot documentation for information about migration.")); +#define EXPERIMENTAL_NODE_WARNING warnings.push_back(RTR("This node is marked as experimental and may be subject to removal or major changes in future versions.")); + #endif // NODE_H