From 2dd043d1f615cfe054c3333319a6e1862955bfee Mon Sep 17 00:00:00 2001 From: Danil Alexeev Date: Wed, 4 Sep 2024 10:54:50 +0300 Subject: [PATCH] Docs: Add missing deprecated/experimental tag support for theme items --- core/doc_data.h | 22 +++++++++++++++ doc/class.xsd | 2 ++ doc/tools/make_rst.py | 8 +++--- editor/doc_tools.cpp | 18 +++++++++++++ editor/editor_help.cpp | 50 ++++++++++++++++++++++++++++++----- editor/editor_help_search.cpp | 2 +- 6 files changed, 91 insertions(+), 11 deletions(-) diff --git a/core/doc_data.h b/core/doc_data.h index 04bd55eabae..6a7f4355db5 100644 --- a/core/doc_data.h +++ b/core/doc_data.h @@ -522,6 +522,10 @@ public: String type; String data_type; String description; + bool is_deprecated = false; + String deprecated_message; + bool is_experimental = false; + String experimental_message; String default_value; String keywords; bool operator<(const ThemeItemDoc &p_theme_item) const { @@ -550,6 +554,16 @@ public: doc.description = p_dict["description"]; } + if (p_dict.has("deprecated")) { + doc.is_deprecated = true; + doc.deprecated_message = p_dict["deprecated"]; + } + + if (p_dict.has("experimental")) { + doc.is_experimental = true; + doc.experimental_message = p_dict["experimental"]; + } + if (p_dict.has("default_value")) { doc.default_value = p_dict["default_value"]; } @@ -579,6 +593,14 @@ public: dict["description"] = p_doc.description; } + if (p_doc.is_deprecated) { + dict["deprecated"] = p_doc.deprecated_message; + } + + if (p_doc.is_experimental) { + dict["experimental"] = p_doc.experimental_message; + } + if (!p_doc.default_value.is_empty()) { dict["default_value"] = p_doc.default_value; } diff --git a/doc/class.xsd b/doc/class.xsd index f0e12410532..28e02e870d9 100644 --- a/doc/class.xsd +++ b/doc/class.xsd @@ -246,6 +246,8 @@ + + diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index 761a7f8f4a1..29e10ea4905 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -1311,9 +1311,6 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: if property_def.text is not None and property_def.text.strip() != "": f.write(f"{format_text_block(property_def.text.strip(), property_def, state)}\n\n") - if property_def.type_name.type_name in PACKED_ARRAY_TYPES: - tmp = f"[b]Note:[/b] The returned array is [i]copied[/i] and any changes to it will not update the original property value. See [{property_def.type_name.type_name}] for more details." - f.write(f"{format_text_block(tmp, property_def, state)}\n\n") elif property_def.deprecated is None and property_def.experimental is None: f.write(".. container:: contribute\n\n\t") f.write( @@ -1323,6 +1320,11 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: + "\n\n" ) + # Add copy note to built-in properties returning `Packed*Array`. + if property_def.type_name.type_name in PACKED_ARRAY_TYPES: + copy_note = f"[b]Note:[/b] The returned array is [i]copied[/i] and any changes to it will not update the original property value. See [{property_def.type_name.type_name}] for more details." + f.write(f"{format_text_block(copy_note, property_def, state)}\n\n") + index += 1 # Constructor, Method, Operator descriptions diff --git a/editor/doc_tools.cpp b/editor/doc_tools.cpp index bf5b717c19d..76934c9ec6e 100644 --- a/editor/doc_tools.cpp +++ b/editor/doc_tools.cpp @@ -277,6 +277,10 @@ static void merge_theme_properties(Vector &p_to, const Ve // Check found entry on name and data type. if (to.name == from.name && to.data_type == from.data_type) { to.description = from.description; + to.is_deprecated = from.is_deprecated; + to.deprecated_message = from.deprecated_message; + to.is_experimental = from.is_experimental; + to.experimental_message = from.experimental_message; to.keywords = from.keywords; } } @@ -1420,6 +1424,14 @@ Error DocTools::_load(Ref parser) { prop2.type = parser->get_named_attribute_value("type"); ERR_FAIL_COND_V(!parser->has_attribute("data_type"), ERR_FILE_CORRUPT); prop2.data_type = parser->get_named_attribute_value("data_type"); + if (parser->has_attribute("deprecated")) { + prop2.is_deprecated = true; + prop2.deprecated_message = parser->get_named_attribute_value("deprecated"); + } + if (parser->has_attribute("experimental")) { + prop2.is_experimental = true; + prop2.experimental_message = parser->get_named_attribute_value("experimental"); + } if (parser->has_attribute("keywords")) { prop2.keywords = parser->get_named_attribute_value("keywords"); } @@ -1738,6 +1750,12 @@ Error DocTools::save_classes(const String &p_default_path, const HashMappush_color(theme_cache.comment_color); + bool has_prev_text = false; + + if (theme_item.is_deprecated) { + has_prev_text = true; + DEPRECATED_DOC_MSG(HANDLE_DOC(theme_item.deprecated_message), TTR("This theme property may be changed or removed in future versions.")); + } + + if (theme_item.is_experimental) { + if (has_prev_text) { + class_desc->add_newline(); + class_desc->add_newline(); + } + has_prev_text = true; + EXPERIMENTAL_DOC_MSG(HANDLE_DOC(theme_item.experimental_message), TTR("This theme property may be changed or removed in future versions.")); + } + const String descr = HANDLE_DOC(theme_item.description); if (!descr.is_empty()) { + if (has_prev_text) { + class_desc->add_newline(); + class_desc->add_newline(); + } + has_prev_text = true; _add_text(descr); - } else { + } else if (!has_prev_text) { class_desc->add_image(get_editor_theme_icon(SNAME("Error"))); class_desc->add_text(" "); class_desc->push_color(theme_cache.comment_color); @@ -2220,12 +2241,6 @@ void EditorHelp::_update_doc() { } has_prev_text = true; _add_text(descr); - // Add copy note to built-in properties returning Packed*Array. - if (!cd.is_script_doc && packed_array_types.has(prop.type)) { - class_desc->add_newline(); - class_desc->add_newline(); - _add_text(vformat(TTR("[b]Note:[/b] The returned array is [i]copied[/i] and any changes to it will not update the original property value. See [%s] for more details."), prop.type)); - } } else if (!has_prev_text) { class_desc->add_image(get_editor_theme_icon(SNAME("Error"))); class_desc->add_text(" "); @@ -2238,6 +2253,13 @@ void EditorHelp::_update_doc() { class_desc->pop(); // color } + // Add copy note to built-in properties returning `Packed*Array`. + if (!cd.is_script_doc && packed_array_types.has(prop.type)) { + class_desc->add_newline(); + class_desc->add_newline(); + _add_text(vformat(TTR("[b]Note:[/b] The returned array is [i]copied[/i] and any changes to it will not update the original property value. See [%s] for more details."), prop.type)); + } + class_desc->pop(); // color _pop_normal_font(); class_desc->pop(); // indent @@ -3380,6 +3402,20 @@ EditorHelpBit::HelpData EditorHelpBit::_get_theme_item_help_data(const StringNam for (const DocData::ThemeItemDoc &theme_item : E->value.theme_properties) { HelpData current; current.description = HANDLE_DOC(theme_item.description); + if (theme_item.is_deprecated) { + if (theme_item.deprecated_message.is_empty()) { + current.deprecated_message = TTR("This theme property may be changed or removed in future versions."); + } else { + current.deprecated_message = HANDLE_DOC(theme_item.deprecated_message); + } + } + if (theme_item.is_experimental) { + if (theme_item.experimental_message.is_empty()) { + current.experimental_message = TTR("This theme property may be changed or removed in future versions."); + } else { + current.experimental_message = HANDLE_DOC(theme_item.experimental_message); + } + } if (theme_item.name == p_theme_item_name) { result = current; diff --git a/editor/editor_help_search.cpp b/editor/editor_help_search.cpp index eb97337b379..987c7f9c31d 100644 --- a/editor/editor_help_search.cpp +++ b/editor/editor_help_search.cpp @@ -1248,7 +1248,7 @@ TreeItem *EditorHelpSearch::Runner::_create_property_item(TreeItem *p_parent, co TreeItem *EditorHelpSearch::Runner::_create_theme_property_item(TreeItem *p_parent, const DocData::ClassDoc *p_class_doc, const MemberMatch &p_match) { String tooltip = p_match.doc->type + " " + p_class_doc->name + "." + p_match.doc->name; tooltip += _build_keywords_tooltip(p_match.doc->keywords); - return _create_member_item(p_parent, p_class_doc->name, SNAME("MemberTheme"), p_match.doc->name, p_match.doc->name, TTRC("Theme Property"), "theme_item", p_match.doc->keywords, tooltip, false, false, p_match.name ? String() : p_match.keyword); + return _create_member_item(p_parent, p_class_doc->name, SNAME("MemberTheme"), p_match.doc->name, p_match.doc->name, TTRC("Theme Property"), "theme_item", p_match.doc->keywords, tooltip, p_match.doc->is_deprecated, p_match.doc->is_experimental, p_match.name ? String() : p_match.keyword); } TreeItem *EditorHelpSearch::Runner::_create_member_item(TreeItem *p_parent, const String &p_class_name, const StringName &p_icon, const String &p_name, const String &p_text, const String &p_type, const String &p_metatype, const String &p_tooltip, const String &p_keywords, bool p_is_deprecated, bool p_is_experimental, const String &p_matching_keyword) {