Skip to content

Commit cb21a20

Browse files
akien-mgaakien-mga
committed
Merge pull request godotengine#96555 from dalexeev/doc-theme-items-deprecated-experimental
Docs: Add missing deprecated/experimental tag support for theme items
2 parents 82799d7 + 2dd043d commit cb21a20

File tree

6 files changed

+91
-11
lines changed

6 files changed

+91
-11
lines changed

‎core/doc_data.h‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -522,6 +522,10 @@ class DocData {
522522
String type;
523523
String data_type;
524524
String description;
525+
bool is_deprecated = false;
526+
String deprecated_message;
527+
bool is_experimental = false;
528+
String experimental_message;
525529
String default_value;
526530
String keywords;
527531
bool operator<(const ThemeItemDoc &p_theme_item) const {
@@ -550,6 +554,16 @@ class DocData {
550554
doc.description = p_dict["description"];
551555
}
552556

557+
if (p_dict.has("deprecated")) {
558+
doc.is_deprecated = true;
559+
doc.deprecated_message = p_dict["deprecated"];
560+
}
561+
562+
if (p_dict.has("experimental")) {
563+
doc.is_experimental = true;
564+
doc.experimental_message = p_dict["experimental"];
565+
}
566+
553567
if (p_dict.has("default_value")) {
554568
doc.default_value = p_dict["default_value"];
555569
}
@@ -579,6 +593,14 @@ class DocData {
579593
dict["description"] = p_doc.description;
580594
}
581595

596+
if (p_doc.is_deprecated) {
597+
dict["deprecated"] = p_doc.deprecated_message;
598+
}
599+
600+
if (p_doc.is_experimental) {
601+
dict["experimental"] = p_doc.experimental_message;
602+
}
603+
582604
if (!p_doc.default_value.is_empty()) {
583605
dict["default_value"] = p_doc.default_value;
584606
}

‎doc/class.xsd‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,8 @@
246246
<xs:attribute type="xs:string" name="data_type" />
247247
<xs:attribute type="xs:string" name="type" />
248248
<xs:attribute type="xs:string" name="default" use="optional" />
249+
<xs:attribute type="xs:string" name="deprecated" use="optional" />
250+
<xs:attribute type="xs:string" name="experimental" use="optional" />
249251
<xs:attribute type="xs:string" name="keywords" use="optional" />
250252
</xs:extension>
251253
</xs:simpleContent>

‎doc/tools/make_rst.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1311,9 +1311,6 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
13111311

13121312
if property_def.text is not None and property_def.text.strip() != "":
13131313
f.write(f"{format_text_block(property_def.text.strip(), property_def, state)}\n\n")
1314-
if property_def.type_name.type_name in PACKED_ARRAY_TYPES:
1315-
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."
1316-
f.write(f"{format_text_block(tmp, property_def, state)}\n\n")
13171314
elif property_def.deprecated is None and property_def.experimental is None:
13181315
f.write(".. container:: contribute\n\n\t")
13191316
f.write(
@@ -1323,6 +1320,11 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
13231320
+ "\n\n"
13241321
)
13251322

1323+
# Add copy note to built-in properties returning `Packed*Array`.
1324+
if property_def.type_name.type_name in PACKED_ARRAY_TYPES:
1325+
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."
1326+
f.write(f"{format_text_block(copy_note, property_def, state)}\n\n")
1327+
13261328
index += 1
13271329

13281330
# Constructor, Method, Operator descriptions

‎editor/doc_tools.cpp‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,10 @@ static void merge_theme_properties(Vector<DocData::ThemeItemDoc> &p_to, const Ve
277277
// Check found entry on name and data type.
278278
if (to.name == from.name && to.data_type == from.data_type) {
279279
to.description = from.description;
280+
to.is_deprecated = from.is_deprecated;
281+
to.deprecated_message = from.deprecated_message;
282+
to.is_experimental = from.is_experimental;
283+
to.experimental_message = from.experimental_message;
280284
to.keywords = from.keywords;
281285
}
282286
}
@@ -1420,6 +1424,14 @@ Error DocTools::_load(Ref<XMLParser> parser) {
14201424
prop2.type = parser->get_named_attribute_value("type");
14211425
ERR_FAIL_COND_V(!parser->has_attribute("data_type"), ERR_FILE_CORRUPT);
14221426
prop2.data_type = parser->get_named_attribute_value("data_type");
1427+
if (parser->has_attribute("deprecated")) {
1428+
prop2.is_deprecated = true;
1429+
prop2.deprecated_message = parser->get_named_attribute_value("deprecated");
1430+
}
1431+
if (parser->has_attribute("experimental")) {
1432+
prop2.is_experimental = true;
1433+
prop2.experimental_message = parser->get_named_attribute_value("experimental");
1434+
}
14231435
if (parser->has_attribute("keywords")) {
14241436
prop2.keywords = parser->get_named_attribute_value("keywords");
14251437
}
@@ -1738,6 +1750,12 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap<String,
17381750
if (!ti.default_value.is_empty()) {
17391751
additional_attributes += String(" default=\"") + ti.default_value.xml_escape(true) + "\"";
17401752
}
1753+
if (ti.is_deprecated) {
1754+
additional_attributes += " deprecated=\"" + ti.deprecated_message.xml_escape(true) + "\"";
1755+
}
1756+
if (ti.is_experimental) {
1757+
additional_attributes += " experimental=\"" + ti.experimental_message.xml_escape(true) + "\"";
1758+
}
17411759
if (!ti.keywords.is_empty()) {
17421760
additional_attributes += String(" keywords=\"") + ti.keywords.xml_escape(true) + "\"";
17431761
}

‎editor/editor_help.cpp‎

Lines changed: 43 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1456,10 +1456,31 @@ void EditorHelp::_update_doc() {
14561456
_push_normal_font();
14571457
class_desc->push_color(theme_cache.comment_color);
14581458

1459+
bool has_prev_text = false;
1460+
1461+
if (theme_item.is_deprecated) {
1462+
has_prev_text = true;
1463+
DEPRECATED_DOC_MSG(HANDLE_DOC(theme_item.deprecated_message), TTR("This theme property may be changed or removed in future versions."));
1464+
}
1465+
1466+
if (theme_item.is_experimental) {
1467+
if (has_prev_text) {
1468+
class_desc->add_newline();
1469+
class_desc->add_newline();
1470+
}
1471+
has_prev_text = true;
1472+
EXPERIMENTAL_DOC_MSG(HANDLE_DOC(theme_item.experimental_message), TTR("This theme property may be changed or removed in future versions."));
1473+
}
1474+
14591475
const String descr = HANDLE_DOC(theme_item.description);
14601476
if (!descr.is_empty()) {
1477+
if (has_prev_text) {
1478+
class_desc->add_newline();
1479+
class_desc->add_newline();
1480+
}
1481+
has_prev_text = true;
14611482
_add_text(descr);
1462-
} else {
1483+
} else if (!has_prev_text) {
14631484
class_desc->add_image(get_editor_theme_icon(SNAME("Error")));
14641485
class_desc->add_text(" ");
14651486
class_desc->push_color(theme_cache.comment_color);
@@ -2220,12 +2241,6 @@ void EditorHelp::_update_doc() {
22202241
}
22212242
has_prev_text = true;
22222243
_add_text(descr);
2223-
// Add copy note to built-in properties returning Packed*Array.
2224-
if (!cd.is_script_doc && packed_array_types.has(prop.type)) {
2225-
class_desc->add_newline();
2226-
class_desc->add_newline();
2227-
_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));
2228-
}
22292244
} else if (!has_prev_text) {
22302245
class_desc->add_image(get_editor_theme_icon(SNAME("Error")));
22312246
class_desc->add_text(" ");
@@ -2238,6 +2253,13 @@ void EditorHelp::_update_doc() {
22382253
class_desc->pop(); // color
22392254
}
22402255

2256+
// Add copy note to built-in properties returning `Packed*Array`.
2257+
if (!cd.is_script_doc && packed_array_types.has(prop.type)) {
2258+
class_desc->add_newline();
2259+
class_desc->add_newline();
2260+
_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));
2261+
}
2262+
22412263
class_desc->pop(); // color
22422264
_pop_normal_font();
22432265
class_desc->pop(); // indent
@@ -3380,6 +3402,20 @@ EditorHelpBit::HelpData EditorHelpBit::_get_theme_item_help_data(const StringNam
33803402
for (const DocData::ThemeItemDoc &theme_item : E->value.theme_properties) {
33813403
HelpData current;
33823404
current.description = HANDLE_DOC(theme_item.description);
3405+
if (theme_item.is_deprecated) {
3406+
if (theme_item.deprecated_message.is_empty()) {
3407+
current.deprecated_message = TTR("This theme property may be changed or removed in future versions.");
3408+
} else {
3409+
current.deprecated_message = HANDLE_DOC(theme_item.deprecated_message);
3410+
}
3411+
}
3412+
if (theme_item.is_experimental) {
3413+
if (theme_item.experimental_message.is_empty()) {
3414+
current.experimental_message = TTR("This theme property may be changed or removed in future versions.");
3415+
} else {
3416+
current.experimental_message = HANDLE_DOC(theme_item.experimental_message);
3417+
}
3418+
}
33833419

33843420
if (theme_item.name == p_theme_item_name) {
33853421
result = current;

‎editor/editor_help_search.cpp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1248,7 +1248,7 @@ TreeItem *EditorHelpSearch::Runner::_create_property_item(TreeItem *p_parent, co
12481248
TreeItem *EditorHelpSearch::Runner::_create_theme_property_item(TreeItem *p_parent, const DocData::ClassDoc *p_class_doc, const MemberMatch<DocData::ThemeItemDoc> &p_match) {
12491249
String tooltip = p_match.doc->type + " " + p_class_doc->name + "." + p_match.doc->name;
12501250
tooltip += _build_keywords_tooltip(p_match.doc->keywords);
1251-
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);
1251+
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);
12521252
}
12531253

12541254
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) {

0 commit comments

Comments
 (0)