godotengine
/
godot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #96555 from dalexeev/doc-theme-items-deprecated-experimental 

Docs: Add missing deprecated/experimental tag support for theme items
This commit is contained in:
Rémi Verschelde 2024-09-04 18:55:49 +02:00
parent 82799d7687 2dd043d1f6
commit cb21a207b3
No known key found for this signature in database
GPG Key ID: C3336907360768E1
6 changed files with 91 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
core/doc_data.h
View File

@ -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;
}

2
doc/class.xsd
View File

@ -246,6 +246,8 @@
<xs:attribute type="xs:string" name="data_type" />
<xs:attribute type="xs:string" name="type" />
<xs:attribute type="xs:string" name="default" use="optional" />
<xs:attribute type="xs:string" name="deprecated" use="optional" />
<xs:attribute type="xs:string" name="experimental" use="optional" />
<xs:attribute type="xs:string" name="keywords" use="optional" />
</xs:extension>
</xs:simpleContent>

8
doc/tools/make_rst.py
View File

@ -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

18
editor/doc_tools.cpp
View File

@ -277,6 +277,10 @@ static void merge_theme_properties(Vector<DocData::ThemeItemDoc> &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<XMLParser> 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 HashMap<String,
if (!ti.default_value.is_empty()) {
additional_attributes += String(" default=\"") + ti.default_value.xml_escape(true) + "\"";
}
if (ti.is_deprecated) {
additional_attributes += " deprecated=\"" + ti.deprecated_message.xml_escape(true) + "\"";
}
if (ti.is_experimental) {
additional_attributes += " experimental=\"" + ti.experimental_message.xml_escape(true) + "\"";
}
if (!ti.keywords.is_empty()) {
additional_attributes += String(" keywords=\"") + ti.keywords.xml_escape(true) + "\"";
}

50
editor/editor_help.cpp
View File

@ -1456,10 +1456,31 @@ void EditorHelp::_update_doc() {
_push_normal_font();
class_desc->push_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;

2
editor/editor_help_search.cpp
View File

@ -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<DocData::ThemeItemDoc> &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) {