summaryrefslogtreecommitdiff
path: root/editor/doc_tools.cpp
diff options
context:
space:
mode:
Diffstat (limited to 'editor/doc_tools.cpp')
-rw-r--r--editor/doc_tools.cpp344
1 files changed, 203 insertions, 141 deletions
diff --git a/editor/doc_tools.cpp b/editor/doc_tools.cpp
index fee2deddda..8191b343f7 100644
--- a/editor/doc_tools.cpp
+++ b/editor/doc_tools.cpp
@@ -41,11 +41,11 @@
#include "scene/resources/theme.h"
// Used for a hack preserving Mono properties on non-Mono builds.
-#include "modules/modules_enabled.gen.h"
+#include "modules/modules_enabled.gen.h" // For mono.
void DocTools::merge_from(const DocTools &p_data) {
- for (Map<String, DocData::ClassDoc>::Element *E = class_list.front(); E; E = E->next()) {
- DocData::ClassDoc &c = E->get();
+ for (KeyValue<String, DocData::ClassDoc> &E : class_list) {
+ DocData::ClassDoc &c = E.value;
if (!p_data.class_list.has(c.name)) {
continue;
@@ -57,25 +57,21 @@ void DocTools::merge_from(const DocTools &p_data) {
c.brief_description = cf.brief_description;
c.tutorials = cf.tutorials;
- for (int i = 0; i < c.methods.size(); i++) {
- DocData::MethodDoc &m = c.methods.write[i];
+ for (int i = 0; i < c.constructors.size(); i++) {
+ DocData::MethodDoc &m = c.constructors.write[i];
- for (int j = 0; j < cf.methods.size(); j++) {
- if (cf.methods[j].name != m.name) {
+ for (int j = 0; j < cf.constructors.size(); j++) {
+ if (cf.constructors[j].name != m.name) {
continue;
}
- const char *operator_prefix = "operator "; // Operators use a space at the end, making this prefix an invalid identifier (and differentiating from methods).
-
- if (cf.methods[j].name == c.name || cf.methods[j].name.begins_with(operator_prefix)) {
- // Since constructors and operators can repeat, we need to check the type of
+ {
+ // Since constructors can repeat, we need to check the type of
// the arguments so we make sure they are different.
-
- if (cf.methods[j].arguments.size() != m.arguments.size()) {
+ if (cf.constructors[j].arguments.size() != m.arguments.size()) {
continue;
}
-
- int arg_count = cf.methods[j].arguments.size();
+ int arg_count = cf.constructors[j].arguments.size();
Vector<bool> arg_used;
arg_used.resize(arg_count);
for (int l = 0; l < arg_count; ++l) {
@@ -85,7 +81,7 @@ void DocTools::merge_from(const DocTools &p_data) {
// have to check one by one so we make sure we have an exact match
for (int k = 0; k < arg_count; ++k) {
for (int l = 0; l < arg_count; ++l) {
- if (cf.methods[j].arguments[k].type == m.arguments[l].type && !arg_used[l]) {
+ if (cf.constructors[j].arguments[k].type == m.arguments[l].type && !arg_used[l]) {
arg_used.write[l] = true;
break;
}
@@ -102,6 +98,21 @@ void DocTools::merge_from(const DocTools &p_data) {
}
}
+ const DocData::MethodDoc &mf = cf.constructors[j];
+
+ m.description = mf.description;
+ break;
+ }
+ }
+
+ for (int i = 0; i < c.methods.size(); i++) {
+ DocData::MethodDoc &m = c.methods.write[i];
+
+ for (int j = 0; j < cf.methods.size(); j++) {
+ if (cf.methods[j].name != m.name) {
+ continue;
+ }
+
const DocData::MethodDoc &mf = cf.methods[j];
m.description = mf.description;
@@ -165,6 +176,54 @@ void DocTools::merge_from(const DocTools &p_data) {
}
}
+ for (int i = 0; i < c.operators.size(); i++) {
+ DocData::MethodDoc &m = c.operators.write[i];
+
+ for (int j = 0; j < cf.operators.size(); j++) {
+ if (cf.operators[j].name != m.name) {
+ continue;
+ }
+
+ {
+ // Since operators can repeat, we need to check the type of
+ // the arguments so we make sure they are different.
+ if (cf.operators[j].arguments.size() != m.arguments.size()) {
+ continue;
+ }
+ int arg_count = cf.operators[j].arguments.size();
+ Vector<bool> arg_used;
+ arg_used.resize(arg_count);
+ for (int l = 0; l < arg_count; ++l) {
+ arg_used.write[l] = false;
+ }
+ // also there is no guarantee that argument ordering will match, so we
+ // have to check one by one so we make sure we have an exact match
+ for (int k = 0; k < arg_count; ++k) {
+ for (int l = 0; l < arg_count; ++l) {
+ if (cf.operators[j].arguments[k].type == m.arguments[l].type && !arg_used[l]) {
+ arg_used.write[l] = true;
+ break;
+ }
+ }
+ }
+ bool not_the_same = false;
+ for (int l = 0; l < arg_count; ++l) {
+ if (!arg_used[l]) { // at least one of the arguments was different
+ not_the_same = true;
+ }
+ }
+ if (not_the_same) {
+ continue;
+ }
+ }
+
+ const DocData::MethodDoc &mf = cf.operators[j];
+
+ m.description = mf.description;
+ break;
+ }
+ }
+
#ifndef MODULE_MONO_ENABLED
// The Mono module defines some properties that we want to keep when
// re-generating docs with a non-Mono build, to prevent pointless diffs
@@ -185,25 +244,25 @@ void DocTools::merge_from(const DocTools &p_data) {
}
void DocTools::remove_from(const DocTools &p_data) {
- for (Map<String, DocData::ClassDoc>::Element *E = p_data.class_list.front(); E; E = E->next()) {
- if (class_list.has(E->key())) {
- class_list.erase(E->key());
+ for (const KeyValue<String, DocData::ClassDoc> &E : p_data.class_list) {
+ if (class_list.has(E.key)) {
+ class_list.erase(E.key);
}
}
}
void DocTools::add_doc(const DocData::ClassDoc &p_class_doc) {
- ERR_FAIL_COND(p_class_doc.name == "");
+ ERR_FAIL_COND(p_class_doc.name.is_empty());
class_list[p_class_doc.name] = p_class_doc;
}
void DocTools::remove_doc(const String &p_class_name) {
- ERR_FAIL_COND(p_class_name == "" || !class_list.has(p_class_name));
+ ERR_FAIL_COND(p_class_name.is_empty() || !class_list.has(p_class_name));
class_list.erase(p_class_name);
}
bool DocTools::has_doc(const String &p_class_name) {
- if (p_class_name == "") {
+ if (p_class_name.is_empty()) {
return false;
}
return class_list.has(p_class_name);
@@ -277,16 +336,22 @@ void DocTools::generate(bool p_basic_types) {
EO = EO->next();
}
- if (E.usage & PROPERTY_USAGE_GROUP || E.usage & PROPERTY_USAGE_SUBGROUP || E.usage & PROPERTY_USAGE_CATEGORY || E.usage & PROPERTY_USAGE_INTERNAL) {
+ if (E.usage & PROPERTY_USAGE_GROUP || E.usage & PROPERTY_USAGE_SUBGROUP || E.usage & PROPERTY_USAGE_CATEGORY || E.usage & PROPERTY_USAGE_INTERNAL || (E.type == Variant::NIL && E.usage & PROPERTY_USAGE_ARRAY)) {
continue;
}
DocData::PropertyDoc prop;
-
prop.name = E.name;
-
prop.overridden = inherited;
+ if (inherited) {
+ String parent = ClassDB::get_parent_class(c.name);
+ while (!ClassDB::has_property(parent, prop.name, true)) {
+ parent = ClassDB::get_parent_class(parent);
+ }
+ prop.overrides = parent;
+ }
+
bool default_value_valid = false;
Variant default_value;
@@ -372,7 +437,7 @@ void DocTools::generate(bool p_basic_types) {
method_list.sort();
for (const MethodInfo &E : method_list) {
- if (E.name == "" || (E.name[0] == '_' && !(E.flags & METHOD_FLAG_VIRTUAL))) {
+ if (E.name.is_empty() || (E.name[0] == '_' && !(E.flags & METHOD_FLAG_VIRTUAL))) {
continue; //hidden, don't count
}
@@ -394,21 +459,21 @@ void DocTools::generate(bool p_basic_types) {
}
if (E.flags & METHOD_FLAG_CONST) {
- if (method.qualifiers != "") {
+ if (!method.qualifiers.is_empty()) {
method.qualifiers += " ";
}
method.qualifiers += "const";
}
if (E.flags & METHOD_FLAG_VARARG) {
- if (method.qualifiers != "") {
+ if (!method.qualifiers.is_empty()) {
method.qualifiers += " ";
}
method.qualifiers += "vararg";
}
if (E.flags & METHOD_FLAG_STATIC) {
- if (method.qualifiers != "") {
+ if (!method.qualifiers.is_empty()) {
method.qualifiers += " ";
}
method.qualifiers += "static";
@@ -544,6 +609,8 @@ void DocTools::generate(bool p_basic_types) {
tid.data_type = "style";
c.theme_properties.push_back(tid);
}
+
+ c.theme_properties.sort();
}
classes.pop_front();
@@ -650,11 +717,6 @@ void DocTools::generate(bool p_basic_types) {
DocData::MethodDoc method;
method.name = mi.name;
- if (method.name == cname) {
- method.qualifiers = "constructor";
- } else if (method.name.begins_with("operator")) {
- method.qualifiers = "operator";
- }
for (int j = 0; j < mi.arguments.size(); j++) {
PropertyInfo arginfo = mi.arguments[j];
@@ -674,27 +736,33 @@ void DocTools::generate(bool p_basic_types) {
DocData::return_doc_from_retinfo(method, mi.return_val);
if (mi.flags & METHOD_FLAG_VARARG) {
- if (method.qualifiers != "") {
+ if (!method.qualifiers.is_empty()) {
method.qualifiers += " ";
}
method.qualifiers += "vararg";
}
if (mi.flags & METHOD_FLAG_CONST) {
- if (method.qualifiers != "") {
+ if (!method.qualifiers.is_empty()) {
method.qualifiers += " ";
}
method.qualifiers += "const";
}
if (mi.flags & METHOD_FLAG_STATIC) {
- if (method.qualifiers != "") {
+ if (!method.qualifiers.is_empty()) {
method.qualifiers += " ";
}
method.qualifiers += "static";
}
- c.methods.push_back(method);
+ if (method.name == cname) {
+ c.constructors.push_back(method);
+ } else if (method.name.begins_with("operator")) {
+ c.operators.push_back(method);
+ } else {
+ c.methods.push_back(method);
+ }
}
List<PropertyInfo> properties;
@@ -817,7 +885,7 @@ void DocTools::generate(bool p_basic_types) {
md.name = mi.name;
if (mi.flags & METHOD_FLAG_VARARG) {
- if (md.qualifiers != "") {
+ if (!md.qualifiers.is_empty()) {
md.qualifiers += " ";
}
md.qualifiers += "vararg";
@@ -916,7 +984,7 @@ static Error _parse_methods(Ref<XMLParser> &parser, Vector<DocData::MethodDoc> &
methods.push_back(method);
} else {
- ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + parser->get_node_name() + ".");
+ ERR_FAIL_V_MSG(ERR_FILE_CORRUPT, "Invalid tag in doc file: " + parser->get_node_name() + ", expected " + element + ".");
}
} else if (parser->get_node_type() == XMLParser::NODE_ELEMENT_END && parser->get_node_name() == section) {
@@ -937,7 +1005,7 @@ Error DocTools::load_classes(const String &p_dir) {
da->list_dir_begin();
String path;
path = da->get_next();
- while (path != String()) {
+ while (!path.is_empty()) {
if (!da->current_is_dir() && path.ends_with("xml")) {
Ref<XMLParser> parser = memnew(XMLParser);
Error err2 = parser->open(p_dir.plus_file(path));
@@ -967,7 +1035,7 @@ Error DocTools::erase_classes(const String &p_dir) {
da->list_dir_begin();
String path;
path = da->get_next();
- while (path != String()) {
+ while (!path.is_empty()) {
if (!da->current_is_dir() && path.ends_with("xml")) {
to_erase.push_back(path);
}
@@ -1044,10 +1112,15 @@ Error DocTools::_load(Ref<XMLParser> parser) {
break; // End of <tutorials>.
}
}
+ } else if (name2 == "constructors") {
+ Error err2 = _parse_methods(parser, c.constructors);
+ ERR_FAIL_COND_V(err2, err2);
} else if (name2 == "methods") {
Error err2 = _parse_methods(parser, c.methods);
ERR_FAIL_COND_V(err2, err2);
-
+ } else if (name2 == "operators") {
+ Error err2 = _parse_methods(parser, c.operators);
+ ERR_FAIL_COND_V(err2, err2);
} else if (name2 == "signals") {
Error err2 = _parse_methods(parser, c.signals);
ERR_FAIL_COND_V(err2, err2);
@@ -1163,7 +1236,7 @@ Error DocTools::_load(Ref<XMLParser> parser) {
}
static void _write_string(FileAccess *f, int p_tablevel, const String &p_string) {
- if (p_string == "") {
+ if (p_string.is_empty()) {
return;
}
String tab;
@@ -1173,9 +1246,62 @@ static void _write_string(FileAccess *f, int p_tablevel, const String &p_string)
f->store_string(tab + p_string + "\n");
}
+static void _write_method_doc(FileAccess *f, const String &p_name, Vector<DocData::MethodDoc> &p_method_docs) {
+ if (!p_method_docs.is_empty()) {
+ p_method_docs.sort();
+ _write_string(f, 1, "<" + p_name + "s>");
+ for (int i = 0; i < p_method_docs.size(); i++) {
+ const DocData::MethodDoc &m = p_method_docs[i];
+
+ String qualifiers;
+ if (!m.qualifiers.is_empty()) {
+ qualifiers += " qualifiers=\"" + m.qualifiers.xml_escape() + "\"";
+ }
+
+ _write_string(f, 2, "<" + p_name + " name=\"" + m.name.xml_escape() + "\"" + qualifiers + ">");
+
+ if (!m.return_type.is_empty()) {
+ String enum_text;
+ if (!m.return_enum.is_empty()) {
+ enum_text = " enum=\"" + m.return_enum + "\"";
+ }
+ _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];
+
+ String enum_text;
+ if (!a.enumeration.is_empty()) {
+ enum_text = " enum=\"" + a.enumeration + "\"";
+ }
+
+ if (!a.default_value.is_empty()) {
+ _write_string(f, 3, "<argument index=\"" + itos(j) + "\" name=\"" + a.name.xml_escape() + "\" type=\"" + a.type.xml_escape() + "\"" + enum_text + " default=\"" + a.default_value.xml_escape(true) + "\" />");
+ } else {
+ _write_string(f, 3, "<argument index=\"" + itos(j) + "\" name=\"" + a.name.xml_escape() + "\" type=\"" + a.type.xml_escape() + "\"" + enum_text + " />");
+ }
+ }
+
+ _write_string(f, 3, "<description>");
+ _write_string(f, 4, m.description.strip_edges().xml_escape());
+ _write_string(f, 3, "</description>");
+
+ _write_string(f, 2, "</" + p_name + ">");
+ }
+
+ _write_string(f, 1, "</" + p_name + "s>");
+ }
+}
+
Error DocTools::save_classes(const String &p_default_path, const Map<String, String> &p_class_path) {
- for (Map<String, DocData::ClassDoc>::Element *E = class_list.front(); E; E = E->next()) {
- DocData::ClassDoc &c = E->get();
+ for (KeyValue<String, DocData::ClassDoc> &E : class_list) {
+ DocData::ClassDoc &c = E.value;
String save_path;
if (p_class_path.has(c.name)) {
@@ -1193,7 +1319,7 @@ Error DocTools::save_classes(const String &p_default_path, const Map<String, Str
_write_string(f, 0, "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>");
String header = "<class name=\"" + c.name + "\"";
- if (c.inherits != "") {
+ if (!c.inherits.is_empty()) {
header += " inherits=\"" + c.inherits + "\"";
}
header += String(" version=\"") + VERSION_BRANCH + "\"";
@@ -1216,75 +1342,28 @@ Error DocTools::save_classes(const String &p_default_path, const Map<String, Str
}
_write_string(f, 1, "</tutorials>");
- _write_string(f, 1, "<methods>");
-
- c.methods.sort();
-
- for (int i = 0; i < c.methods.size(); i++) {
- const DocData::MethodDoc &m = c.methods[i];
-
- String qualifiers;
- if (m.qualifiers != "") {
- qualifiers += " qualifiers=\"" + m.qualifiers.xml_escape() + "\"";
- }
-
- _write_string(f, 2, "<method name=\"" + m.name.xml_escape() + "\"" + qualifiers + ">");
-
- if (m.return_type != "") {
- String enum_text;
- if (m.return_enum != String()) {
- enum_text = " enum=\"" + m.return_enum + "\"";
- }
- _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];
-
- String enum_text;
- if (a.enumeration != String()) {
- enum_text = " enum=\"" + a.enumeration + "\"";
- }
-
- if (a.default_value != "") {
- _write_string(f, 3, "<argument index=\"" + itos(j) + "\" name=\"" + a.name.xml_escape() + "\" type=\"" + a.type.xml_escape() + "\"" + enum_text + " default=\"" + a.default_value.xml_escape(true) + "\" />");
- } else {
- _write_string(f, 3, "<argument index=\"" + itos(j) + "\" name=\"" + a.name.xml_escape() + "\" type=\"" + a.type.xml_escape() + "\"" + enum_text + " />");
- }
- }
+ _write_method_doc(f, "constructor", c.constructors);
- _write_string(f, 3, "<description>");
- _write_string(f, 4, m.description.strip_edges().xml_escape());
- _write_string(f, 3, "</description>");
+ _write_method_doc(f, "method", c.methods);
- _write_string(f, 2, "</method>");
- }
-
- _write_string(f, 1, "</methods>");
-
- if (c.properties.size()) {
+ if (!c.properties.is_empty()) {
_write_string(f, 1, "<members>");
c.properties.sort();
for (int i = 0; i < c.properties.size(); i++) {
String additional_attributes;
- if (c.properties[i].enumeration != String()) {
+ if (!c.properties[i].enumeration.is_empty()) {
additional_attributes += " enum=\"" + c.properties[i].enumeration + "\"";
}
- if (c.properties[i].default_value != String()) {
+ if (!c.properties[i].default_value.is_empty()) {
additional_attributes += " default=\"" + c.properties[i].default_value.xml_escape(true) + "\"";
}
const DocData::PropertyDoc &p = c.properties[i];
if (c.properties[i].overridden) {
- _write_string(f, 2, "<member name=\"" + p.name + "\" type=\"" + p.type + "\" setter=\"" + p.setter + "\" getter=\"" + p.getter + "\" override=\"true\"" + additional_attributes + " />");
+ _write_string(f, 2, "<member name=\"" + p.name + "\" type=\"" + p.type + "\" setter=\"" + p.setter + "\" getter=\"" + p.getter + "\" overrides=\"" + p.overrides + "\"" + additional_attributes + " />");
} else {
_write_string(f, 2, "<member name=\"" + p.name + "\" type=\"" + p.type + "\" setter=\"" + p.setter + "\" getter=\"" + p.getter + "\"" + additional_attributes + ">");
_write_string(f, 3, p.description.strip_edges().xml_escape());
@@ -1294,59 +1373,40 @@ Error DocTools::save_classes(const String &p_default_path, const Map<String, Str
_write_string(f, 1, "</members>");
}
- if (c.signals.size()) {
- c.signals.sort();
-
- _write_string(f, 1, "<signals>");
- for (int i = 0; i < c.signals.size(); i++) {
- const DocData::MethodDoc &m = c.signals[i];
- _write_string(f, 2, "<signal name=\"" + m.name + "\">");
- for (int j = 0; j < m.arguments.size(); j++) {
- const DocData::ArgumentDoc &a = m.arguments[j];
- _write_string(f, 3, "<argument index=\"" + itos(j) + "\" name=\"" + a.name.xml_escape() + "\" type=\"" + a.type.xml_escape() + "\" />");
- }
-
- _write_string(f, 3, "<description>");
- _write_string(f, 4, m.description.strip_edges().xml_escape());
- _write_string(f, 3, "</description>");
+ _write_method_doc(f, "signal", c.signals);
- _write_string(f, 2, "</signal>");
- }
-
- _write_string(f, 1, "</signals>");
- }
-
- _write_string(f, 1, "<constants>");
-
- for (int i = 0; i < c.constants.size(); i++) {
- const DocData::ConstantDoc &k = c.constants[i];
- if (k.is_value_valid) {
- if (k.enumeration != String()) {
- _write_string(f, 2, "<constant name=\"" + k.name + "\" value=\"" + k.value + "\" enum=\"" + k.enumeration + "\">");
- } else {
- _write_string(f, 2, "<constant name=\"" + k.name + "\" value=\"" + k.value + "\">");
- }
- } else {
- if (k.enumeration != String()) {
- _write_string(f, 2, "<constant name=\"" + k.name + "\" value=\"platform-dependent\" enum=\"" + k.enumeration + "\">");
+ if (!c.constants.is_empty()) {
+ _write_string(f, 1, "<constants>");
+ for (int i = 0; i < c.constants.size(); i++) {
+ const DocData::ConstantDoc &k = c.constants[i];
+ if (k.is_value_valid) {
+ if (!k.enumeration.is_empty()) {
+ _write_string(f, 2, "<constant name=\"" + k.name + "\" value=\"" + k.value + "\" enum=\"" + k.enumeration + "\">");
+ } else {
+ _write_string(f, 2, "<constant name=\"" + k.name + "\" value=\"" + k.value + "\">");
+ }
} else {
- _write_string(f, 2, "<constant name=\"" + k.name + "\" value=\"platform-dependent\">");
+ if (!k.enumeration.is_empty()) {
+ _write_string(f, 2, "<constant name=\"" + k.name + "\" value=\"platform-dependent\" enum=\"" + k.enumeration + "\">");
+ } else {
+ _write_string(f, 2, "<constant name=\"" + k.name + "\" value=\"platform-dependent\">");
+ }
}
+ _write_string(f, 3, k.description.strip_edges().xml_escape());
+ _write_string(f, 2, "</constant>");
}
- _write_string(f, 3, k.description.strip_edges().xml_escape());
- _write_string(f, 2, "</constant>");
- }
- _write_string(f, 1, "</constants>");
+ _write_string(f, 1, "</constants>");
+ }
- if (c.theme_properties.size()) {
+ if (!c.theme_properties.is_empty()) {
c.theme_properties.sort();
_write_string(f, 1, "<theme_items>");
for (int i = 0; i < c.theme_properties.size(); i++) {
const DocData::ThemeItemDoc &ti = c.theme_properties[i];
- if (ti.default_value != "") {
+ if (!ti.default_value.is_empty()) {
_write_string(f, 2, "<theme_item name=\"" + ti.name + "\" data_type=\"" + ti.data_type + "\" type=\"" + ti.type + "\" default=\"" + ti.default_value.xml_escape(true) + "\">");
} else {
_write_string(f, 2, "<theme_item name=\"" + ti.name + "\" data_type=\"" + ti.data_type + "\" type=\"" + ti.type + "\">");
@@ -1359,6 +1419,8 @@ Error DocTools::save_classes(const String &p_default_path, const Map<String, Str
_write_string(f, 1, "</theme_items>");
}
+ _write_method_doc(f, "operator", c.operators);
+
_write_string(f, 0, "</class>");
}
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-26 23:38:53 +0000