Merge pull request #62713 from YuriSizov/docs-scripting-annotations

4 files changed, 185 insertions, 16 deletions

diff --git a/editor/doc_tools.cpp b/editor/doc_tools.cpp
index 88818bfca4..a6c7970264 100644
--- a/editor/doc_tools.cpp
+++ b/editor/doc_tools.cpp
@@ -178,6 +178,20 @@ void DocTools::merge_from(const DocTools &p_data) {
 			}
 		}
 
+		for (int i = 0; i < c.annotations.size(); i++) {
+			DocData::MethodDoc &m = c.annotations.write[i];
+
+			for (int j = 0; j < cf.annotations.size(); j++) {
+				if (cf.annotations[j].name != m.name) {
+					continue;
+				}
+				const DocData::MethodDoc &mf = cf.annotations[j];
+
+				m.description = mf.description;
+				break;
+			}
+		}
+
 		for (int i = 0; i < c.properties.size(); i++) {
 			DocData::PropertyDoc &p = c.properties.write[i];
 
@@ -960,8 +974,41 @@ void DocTools::generate(bool p_basic_types) {
 				c.constants.push_back(cd);
 			}
 
+			// Get annotations.
+			List<MethodInfo> ainfo;
+			lang->get_public_annotations(&ainfo);
+
+			for (const MethodInfo &ai : ainfo) {
+				DocData::MethodDoc atd;
+				atd.name = ai.name;
+
+				if (ai.flags & METHOD_FLAG_VARARG) {
+					if (!atd.qualifiers.is_empty()) {
+						atd.qualifiers += " ";
+					}
+					atd.qualifiers += "vararg";
+				}
+
+				DocData::return_doc_from_retinfo(atd, ai.return_val);
+
+				for (int j = 0; j < ai.arguments.size(); j++) {
+					DocData::ArgumentDoc ad;
+					DocData::argument_doc_from_arginfo(ad, ai.arguments[j]);
+
+					int darg_idx = j - (ai.arguments.size() - ai.default_arguments.size());
+					if (darg_idx >= 0) {
+						Variant default_arg = ai.default_arguments[darg_idx];
+						ad.default_value = default_arg.get_construct_string().replace("\n", " ");
+					}
+
+					atd.arguments.push_back(ad);
+				}
+
+				c.annotations.push_back(atd);
+			}
+
 			// Skip adding the lang if it doesn't expose anything (e.g. C#).
-			if (c.methods.is_empty() && c.constants.is_empty()) {
+			if (c.methods.is_empty() && c.constants.is_empty() && c.annotations.is_empty()) {
 				continue;
 			}
 
@@ -1163,6 +1210,9 @@ Error DocTools::_load(Ref<XMLParser> parser) {
 				} else if (name2 == "signals") {
 					Error err2 = _parse_methods(parser, c.signals);
 					ERR_FAIL_COND_V(err2, err2);
+				} else if (name2 == "annotations") {
+					Error err2 = _parse_methods(parser, c.annotations);
+					ERR_FAIL_COND_V(err2, err2);
 				} else if (name2 == "members") {
 					while (parser->read() == OK) {
 						if (parser->get_node_type() == XMLParser::NODE_ELEMENT) {
@@ -1450,6 +1500,8 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap<String,
 			_write_string(f, 1, "</constants>");
 		}
 
+		_write_method_doc(f, "annotation", c.annotations);
+
 		if (!c.theme_properties.is_empty()) {
 			c.theme_properties.sort();
 
diff --git a/editor/editor_help.cpp b/editor/editor_help.cpp
index 7bf9eb2997..48d4b96a67 100644
--- a/editor/editor_help.cpp
+++ b/editor/editor_help.cpp
@@ -125,6 +125,9 @@ void EditorHelp::_class_desc_select(const String &p_select) {
 		} else if (tag == "constant") {
 			topic = "class_constant";
 			table = &this->constant_line;
+		} else if (tag == "annotation") {
+			topic = "class_annotation";
+			table = &this->annotation_line;
 		} else if (tag == "theme_item") {
 			topic = "theme_item";
 			table = &this->theme_property_line;
@@ -274,7 +277,7 @@ void EditorHelp::_add_method(const DocData::MethodDoc &p_method, bool p_overview
 		class_desc->add_text(" ");
 	}
 
-	if (p_overview && !p_method.description.is_empty()) {
+	if (p_overview && !p_method.description.strip_edges().is_empty()) {
 		class_desc->push_meta("@method " + p_method.name);
 	}
 
@@ -282,7 +285,7 @@ void EditorHelp::_add_method(const DocData::MethodDoc &p_method, bool p_overview
 	_add_text(p_method.name);
 	class_desc->pop();
 
-	if (p_overview && !p_method.description.is_empty()) {
+	if (p_overview && !p_method.description.strip_edges().is_empty()) {
 		class_desc->pop(); //meta
 	}
 
@@ -412,7 +415,7 @@ void EditorHelp::_update_method_list(const Vector<DocData::MethodDoc> p_methods,
 				class_desc->pop(); //cell
 			}
 
-			if (!m[i].description.is_empty() || m[i].errors_returned.size() > 0) {
+			if (!m[i].description.strip_edges().is_empty() || m[i].errors_returned.size() > 0) {
 				r_method_descrpitons = true;
 			}
 
@@ -611,7 +614,7 @@ void EditorHelp::_update_doc() {
 	class_desc->add_newline();
 
 	// Brief description
-	if (!cd.brief_description.is_empty()) {
+	if (!cd.brief_description.strip_edges().is_empty()) {
 		class_desc->push_color(text_color);
 		class_desc->push_font(doc_bold_font);
 		class_desc->push_indent(1);
@@ -625,7 +628,7 @@ void EditorHelp::_update_doc() {
 	}
 
 	// Class description
-	if (!cd.description.is_empty()) {
+	if (!cd.description.strip_edges().is_empty()) {
 		section_line.push_back(Pair<String, int>(TTR("Description"), class_desc->get_paragraph_count() - 2));
 		description_line = class_desc->get_paragraph_count() - 2;
 		class_desc->push_color(title_color);
@@ -692,7 +695,7 @@ void EditorHelp::_update_doc() {
 	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.is_empty()) {
+			if (cd.properties[i].name.begins_with("_") && cd.properties[i].description.strip_edges().is_empty()) {
 				continue;
 			}
 			has_properties = true;
@@ -718,7 +721,7 @@ void EditorHelp::_update_doc() {
 
 		for (int i = 0; i < cd.properties.size(); i++) {
 			// Ignore undocumented private.
-			if (cd.properties[i].name.begins_with("_") && cd.properties[i].description.is_empty()) {
+			if (cd.properties[i].name.begins_with("_") && cd.properties[i].description.strip_edges().is_empty()) {
 				continue;
 			}
 			property_line[cd.properties[i].name] = class_desc->get_paragraph_count() - 2; //gets overridden if description
@@ -743,7 +746,7 @@ void EditorHelp::_update_doc() {
 				describe = true;
 			}
 
-			if (!cd.properties[i].description.is_empty()) {
+			if (!cd.properties[i].description.strip_edges().is_empty()) {
 				describe = true;
 			}
 
@@ -856,7 +859,7 @@ void EditorHelp::_update_doc() {
 			}
 		}
 		// Ignore undocumented non virtual private.
-		if (cd.methods[i].name.begins_with("_") && cd.methods[i].description.is_empty() && !cd.methods[i].qualifiers.contains("virtual")) {
+		if (cd.methods[i].name.begins_with("_") && cd.methods[i].description.strip_edges().is_empty() && !cd.methods[i].qualifiers.contains("virtual")) {
 			continue;
 		}
 		methods.push_back(cd.methods[i]);
@@ -976,7 +979,7 @@ void EditorHelp::_update_doc() {
 			class_desc->pop(); // monofont
 
 			// Theme item description.
-			if (!cd.theme_properties[i].description.is_empty()) {
+			if (!cd.theme_properties[i].description.strip_edges().is_empty()) {
 				class_desc->push_font(doc_font);
 				class_desc->push_color(comment_color);
 				class_desc->push_indent(1);
@@ -1018,8 +1021,8 @@ void EditorHelp::_update_doc() {
 			signal_line[cd.signals[i].name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description.
 
 			class_desc->push_font(doc_code_font); // monofont
-			class_desc->push_color(headline_color);
 			_add_bulletpoint();
+			class_desc->push_color(headline_color);
 			_add_text(cd.signals[i].name);
 			class_desc->pop();
 			class_desc->push_color(symbol_color);
@@ -1048,7 +1051,7 @@ void EditorHelp::_update_doc() {
 			class_desc->add_text(")");
 			class_desc->pop();
 			class_desc->pop(); // end monofont
-			if (!cd.signals[i].description.is_empty()) {
+			if (!cd.signals[i].description.strip_edges().is_empty()) {
 				class_desc->push_font(doc_font);
 				class_desc->push_color(comment_color);
 				class_desc->push_indent(1);
@@ -1079,7 +1082,7 @@ void EditorHelp::_update_doc() {
 				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.is_empty()) {
+				if (cd.constants[i].name.begins_with("_") && cd.constants[i].description.strip_edges().is_empty()) {
 					continue;
 				}
 				constants.push_back(cd.constants[i]);
@@ -1155,8 +1158,8 @@ void EditorHelp::_update_doc() {
 					constant_line[enum_list[i].name] = class_desc->get_paragraph_count() - 2;
 
 					class_desc->push_font(doc_code_font);
-					class_desc->push_color(headline_color);
 					_add_bulletpoint();
+					class_desc->push_color(headline_color);
 					_add_text(enum_list[i].name);
 					class_desc->pop();
 					class_desc->push_color(symbol_color);
@@ -1240,7 +1243,7 @@ void EditorHelp::_update_doc() {
 
 				class_desc->add_newline();
 
-				if (!constants[i].description.is_empty()) {
+				if (!constants[i].description.strip_edges().is_empty()) {
 					class_desc->push_font(doc_font);
 					class_desc->push_color(comment_color);
 					_add_text(DTR(constants[i].description));
@@ -1259,6 +1262,112 @@ void EditorHelp::_update_doc() {
 		}
 	}
 
+	// Annotations
+	if (!cd.annotations.is_empty()) {
+		if (sort_methods) {
+			cd.annotations.sort();
+		}
+
+		section_line.push_back(Pair<String, int>(TTR("Annotations"), class_desc->get_paragraph_count() - 2));
+		class_desc->push_color(title_color);
+		class_desc->push_font(doc_title_font);
+		class_desc->push_font_size(doc_title_font_size);
+		class_desc->add_text(TTR("Annotations"));
+		class_desc->pop(); // font size
+		class_desc->pop(); // font
+		class_desc->pop(); // color
+
+		class_desc->add_newline();
+		class_desc->add_newline();
+
+		class_desc->push_indent(1);
+
+		for (int i = 0; i < cd.annotations.size(); i++) {
+			annotation_line[cd.annotations[i].name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description.
+
+			class_desc->push_font(doc_code_font); // monofont
+			_add_bulletpoint();
+			class_desc->push_color(headline_color);
+			_add_text(cd.annotations[i].name);
+			class_desc->pop();
+
+			if (cd.annotations[i].arguments.size() > 0) {
+				class_desc->push_color(symbol_color);
+				class_desc->add_text("(");
+				class_desc->pop();
+				for (int j = 0; j < cd.annotations[i].arguments.size(); j++) {
+					class_desc->push_color(text_color);
+					if (j > 0) {
+						class_desc->add_text(", ");
+					}
+
+					_add_text(cd.annotations[i].arguments[j].name);
+					class_desc->add_text(": ");
+					_add_type(cd.annotations[i].arguments[j].type);
+					if (!cd.annotations[i].arguments[j].default_value.is_empty()) {
+						class_desc->push_color(symbol_color);
+						class_desc->add_text(" = ");
+						class_desc->pop();
+						_add_text(cd.annotations[i].arguments[j].default_value);
+					}
+
+					class_desc->pop();
+				}
+
+				if (cd.annotations[i].qualifiers.contains("vararg")) {
+					class_desc->push_color(text_color);
+					if (cd.annotations[i].arguments.size()) {
+						class_desc->add_text(", ");
+					}
+					class_desc->push_color(symbol_color);
+					class_desc->add_text("...");
+					class_desc->pop();
+					class_desc->pop();
+				}
+
+				class_desc->push_color(symbol_color);
+				class_desc->add_text(")");
+				class_desc->pop();
+			}
+
+			if (!cd.annotations[i].qualifiers.is_empty()) {
+				class_desc->push_color(qualifier_color);
+				class_desc->add_text(" ");
+				_add_text(cd.annotations[i].qualifiers);
+				class_desc->pop();
+			}
+
+			class_desc->pop(); // end monofont
+
+			if (!cd.annotations[i].description.strip_edges().is_empty()) {
+				class_desc->push_font(doc_font);
+				class_desc->push_color(comment_color);
+				class_desc->push_indent(1);
+				_add_text(DTR(cd.annotations[i].description));
+				class_desc->pop(); // indent
+				class_desc->pop();
+				class_desc->pop(); // font
+			} else {
+				class_desc->push_indent(1);
+				class_desc->add_image(get_theme_icon(SNAME("Error"), SNAME("EditorIcons")));
+				class_desc->add_text(" ");
+				class_desc->push_color(comment_color);
+				if (cd.is_script_doc) {
+					class_desc->append_text(TTR("There is currently no description for this annotation."));
+				} else {
+					class_desc->append_text(TTR("There is currently no description for this annotation. 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(); // indent
+			}
+			class_desc->add_newline();
+			class_desc->add_newline();
+		}
+
+		class_desc->pop();
+		class_desc->add_newline();
+	}
+
 	// Property descriptions
 	if (property_descr) {
 		section_line.push_back(Pair<String, int>(TTR("Property Descriptions"), class_desc->get_paragraph_count() - 2));
@@ -1505,6 +1614,10 @@ void EditorHelp::_help_callback(const String &p_topic) {
 		if (constant_line.has(name)) {
 			line = constant_line[name];
 		}
+	} else if (what == "class_annotation") {
+		if (annotation_line.has(name)) {
+			line = annotation_line[name];
+		}
 	} else if (what == "class_global") {
 		if (constant_line.has(name)) {
 			line = constant_line[name];
diff --git a/editor/editor_help.h b/editor/editor_help.h
index 7f91a8102d..9f8da938f1 100644
--- a/editor/editor_help.h
+++ b/editor/editor_help.h
@@ -110,6 +110,7 @@ class EditorHelp : public VBoxContainer {
 	HashMap<String, int> property_line;
 	HashMap<String, int> theme_property_line;
 	HashMap<String, int> constant_line;
+	HashMap<String, int> annotation_line;
 	HashMap<String, int> enum_line;
 	HashMap<String, HashMap<String, int>> enum_values_line;
 	int description_line = 0;
diff --git a/editor/plugins/script_text_editor.cpp b/editor/plugins/script_text_editor.cpp
index 7d4ffd1a25..7c3520c39d 100644
--- a/editor/plugins/script_text_editor.cpp
+++ b/editor/plugins/script_text_editor.cpp
@@ -886,6 +886,9 @@ void ScriptTextEditor::_lookup_symbol(const String &p_symbol, int p_row, int p_c
 				emit_signal(SNAME("go_to_help"), "class_enum:" + result.class_name + ":" + result.class_member);
 
 			} break;
+			case ScriptLanguage::LOOKUP_RESULT_CLASS_ANNOTATION: {
+				emit_signal(SNAME("go_to_help"), "class_annotation:" + result.class_name + ":" + result.class_member);
+			} break;
 			case ScriptLanguage::LOOKUP_RESULT_CLASS_TBD_GLOBALSCOPE: {
 				emit_signal(SNAME("go_to_help"), "class_global:" + result.class_name + ":" + result.class_member);
 			} break;