From 96f8254b24109884bdc3f6a7e224a8045b27ee15 Mon Sep 17 00:00:00 2001
From: reduz <reduzio@gmail.com>
Date: Tue, 24 Aug 2021 15:16:25 -0300
Subject: Implement error return documetation

Adds ability to add error return documetation to the binder and class reference.
Usage example:

```C++
void MyClass::_bind_method() {
	[..]
	BIND_METHOD_ERR_RETURN_DOC("load", ERR_FILE_CANT_OPEN, ERR_FILE_UNRECOGNIZED);
}
```

One function of ConfigFile was changed as example.
---
 editor/doc_tools.cpp   | 20 ++++++++++++++++++++
 editor/editor_help.cpp | 28 +++++++++++++++++++++++++++-
 2 files changed, 47 insertions(+), 1 deletion(-)

(limited to 'editor')

diff --git a/editor/doc_tools.cpp b/editor/doc_tools.cpp
index fb5f7448c4..fee2deddda 100644
--- a/editor/doc_tools.cpp
+++ b/editor/doc_tools.cpp
@@ -434,6 +434,18 @@ void DocTools::generate(bool p_basic_types) {
 				}
 			}
 
+			Vector<Error> errs = ClassDB::get_method_error_return_values(name, E.name);
+			if (errs.size()) {
+				if (errs.find(OK) == -1) {
+					errs.insert(0, OK);
+				}
+				for (int i = 0; i < errs.size(); i++) {
+					if (method.errors_returned.find(errs[i]) == -1) {
+						method.errors_returned.push_back(errs[i]);
+					}
+				}
+			}
+
 			c.methods.push_back(method);
 		}
 
@@ -874,6 +886,9 @@ static Error _parse_methods(Ref<XMLParser> &parser, Vector<DocData::MethodDoc> &
 							if (parser->has_attribute("enum")) {
 								method.return_enum = parser->get_attribute_value("enum");
 							}
+						} else if (name == "returns_error") {
+							ERR_FAIL_COND_V(!parser->has_attribute("number"), ERR_FILE_CORRUPT);
+							method.errors_returned.push_back(parser->get_attribute_value("number").to_int());
 						} else if (name == "argument") {
 							DocData::ArgumentDoc argument;
 							ERR_FAIL_COND_V(!parser->has_attribute("name"), ERR_FILE_CORRUPT);
@@ -1222,6 +1237,11 @@ Error DocTools::save_classes(const String &p_default_path, const Map<String, Str
 				}
 				_write_string(f, 3, "<return type=\"" + m.return_type + "\"" + enum_text + " />");
 			}
+			if (m.errors_returned.size() > 0) {
+				for (int j = 0; j < m.errors_returned.size(); j++) {
+					_write_string(f, 3, "<returns_error number=\"" + itos(m.errors_returned[j]) + "\"/>");
+				}
+			}
 
 			for (int j = 0; j < m.arguments.size(); j++) {
 				const DocData::ArgumentDoc &a = m.arguments[j];
diff --git a/editor/editor_help.cpp b/editor/editor_help.cpp
index 16151e36de..24b6ba1a14 100644
--- a/editor/editor_help.cpp
+++ b/editor/editor_help.cpp
@@ -30,6 +30,7 @@
 
 #include "editor_help.h"
 
+#include "core/core_constants.h"
 #include "core/input/input.h"
 #include "core/os/keyboard.h"
 #include "doc_data_compressed.gen.h"
@@ -695,7 +696,7 @@ void EditorHelp::_update_doc() {
 					class_desc->pop(); //cell
 				}
 
-				if (m[i].description != "") {
+				if (m[i].description != "" || m[i].errors_returned.size() > 0) {
 					method_descr = true;
 				}
 
@@ -1227,6 +1228,31 @@ void EditorHelp::_update_doc() {
 				class_desc->push_color(text_color);
 				class_desc->push_font(doc_font);
 				class_desc->push_indent(1);
+				if (methods_filtered[i].errors_returned.size()) {
+					class_desc->append_bbcode(TTR("Error codes returned:"));
+					class_desc->add_newline();
+					class_desc->push_list(0, RichTextLabel::LIST_DOTS, false);
+					for (int j = 0; j < methods_filtered[i].errors_returned.size(); j++) {
+						if (j > 0) {
+							class_desc->add_newline();
+						}
+						int val = methods_filtered[i].errors_returned[j];
+						String text = itos(val);
+						for (int k = 0; k < CoreConstants::get_global_constant_count(); k++) {
+							if (CoreConstants::get_global_constant_value(k) == val && CoreConstants::get_global_constant_enum(k) == SNAME("Error")) {
+								text = CoreConstants::get_global_constant_name(k);
+								break;
+							}
+						}
+
+						class_desc->push_bold();
+						class_desc->append_bbcode(text);
+						class_desc->pop();
+					}
+					class_desc->pop();
+					class_desc->add_newline();
+					class_desc->add_newline();
+				}
 				if (!methods_filtered[i].description.strip_edges().is_empty()) {
 					_add_text(DTR(methods_filtered[i].description));
 				} else {
-- 
cgit v1.2.3