mirror of
https://github.com/godotengine/godot
synced 2024-09-05 10:08:45 +00:00
doc: Fixups to #43419 which added operators in the docs
- Escape the method names as e.g. `operator <` is invalid XML. - Add a hack to merge all String % operator definitions for each Variant type as a single one with `Variant` argument type. - Add support for the new qualifiers in makerst.py. - Drop unused `doc_merge.py`, seems to date back to when we had all the documentation in a single `classes.xml`.
This commit is contained in:
parent
0efe6dff5f
commit
34cad0d020
|
@ -1,237 +0,0 @@
|
||||||
#!/usr/bin/env python
|
|
||||||
# -*- coding: utf-8 -*-
|
|
||||||
|
|
||||||
import sys
|
|
||||||
import xml.etree.ElementTree as ET
|
|
||||||
|
|
||||||
|
|
||||||
tree = ET.parse(sys.argv[1])
|
|
||||||
old_doc = tree.getroot()
|
|
||||||
|
|
||||||
tree = ET.parse(sys.argv[2])
|
|
||||||
new_doc = tree.getroot()
|
|
||||||
|
|
||||||
f = file(sys.argv[3], "wb")
|
|
||||||
tab = 0
|
|
||||||
|
|
||||||
old_classes = {}
|
|
||||||
|
|
||||||
|
|
||||||
def write_string(_f, text, newline=True):
|
|
||||||
for t in range(tab):
|
|
||||||
_f.write("\t")
|
|
||||||
_f.write(text)
|
|
||||||
if newline:
|
|
||||||
_f.write("\n")
|
|
||||||
|
|
||||||
|
|
||||||
def escape(ret):
|
|
||||||
ret = ret.replace("&", "&")
|
|
||||||
ret = ret.replace("<", ">")
|
|
||||||
ret = ret.replace(">", "<")
|
|
||||||
ret = ret.replace("'", "'")
|
|
||||||
ret = ret.replace('"', """)
|
|
||||||
return ret
|
|
||||||
|
|
||||||
|
|
||||||
def inc_tab():
|
|
||||||
global tab
|
|
||||||
tab += 1
|
|
||||||
|
|
||||||
|
|
||||||
def dec_tab():
|
|
||||||
global tab
|
|
||||||
tab -= 1
|
|
||||||
|
|
||||||
|
|
||||||
write_string(f, '<?xml version="1.0" encoding="UTF-8" ?>')
|
|
||||||
write_string(f, '<doc version="' + new_doc.attrib["version"] + '">')
|
|
||||||
|
|
||||||
|
|
||||||
def get_tag(node, name):
|
|
||||||
tag = ""
|
|
||||||
if name in node.attrib:
|
|
||||||
tag = " " + name + '="' + escape(node.attrib[name]) + '" '
|
|
||||||
return tag
|
|
||||||
|
|
||||||
|
|
||||||
def find_method_descr(old_class, name):
|
|
||||||
|
|
||||||
methods = old_class.find("methods")
|
|
||||||
if methods != None and len(list(methods)) > 0:
|
|
||||||
for m in list(methods):
|
|
||||||
if m.attrib["name"] == name:
|
|
||||||
description = m.find("description")
|
|
||||||
if description != None and description.text.strip() != "":
|
|
||||||
return description.text
|
|
||||||
|
|
||||||
return None
|
|
||||||
|
|
||||||
|
|
||||||
def find_signal_descr(old_class, name):
|
|
||||||
|
|
||||||
signals = old_class.find("signals")
|
|
||||||
if signals != None and len(list(signals)) > 0:
|
|
||||||
for m in list(signals):
|
|
||||||
if m.attrib["name"] == name:
|
|
||||||
description = m.find("description")
|
|
||||||
if description != None and description.text.strip() != "":
|
|
||||||
return description.text
|
|
||||||
|
|
||||||
return None
|
|
||||||
|
|
||||||
|
|
||||||
def find_constant_descr(old_class, name):
|
|
||||||
|
|
||||||
if old_class is None:
|
|
||||||
return None
|
|
||||||
constants = old_class.find("constants")
|
|
||||||
if constants != None and len(list(constants)) > 0:
|
|
||||||
for m in list(constants):
|
|
||||||
if m.attrib["name"] == name:
|
|
||||||
if m.text.strip() != "":
|
|
||||||
return m.text
|
|
||||||
return None
|
|
||||||
|
|
||||||
|
|
||||||
def write_class(c):
|
|
||||||
class_name = c.attrib["name"]
|
|
||||||
print("Parsing Class: " + class_name)
|
|
||||||
if class_name in old_classes:
|
|
||||||
old_class = old_classes[class_name]
|
|
||||||
else:
|
|
||||||
old_class = None
|
|
||||||
|
|
||||||
category = get_tag(c, "category")
|
|
||||||
inherits = get_tag(c, "inherits")
|
|
||||||
write_string(f, '<class name="' + class_name + '" ' + category + inherits + ">")
|
|
||||||
inc_tab()
|
|
||||||
|
|
||||||
write_string(f, "<brief_description>")
|
|
||||||
|
|
||||||
if old_class != None:
|
|
||||||
old_brief_descr = old_class.find("brief_description")
|
|
||||||
if old_brief_descr != None:
|
|
||||||
write_string(f, escape(old_brief_descr.text.strip()))
|
|
||||||
|
|
||||||
write_string(f, "</brief_description>")
|
|
||||||
|
|
||||||
write_string(f, "<description>")
|
|
||||||
if old_class != None:
|
|
||||||
old_descr = old_class.find("description")
|
|
||||||
if old_descr != None:
|
|
||||||
write_string(f, escape(old_descr.text.strip()))
|
|
||||||
|
|
||||||
write_string(f, "</description>")
|
|
||||||
|
|
||||||
methods = c.find("methods")
|
|
||||||
if methods != None and len(list(methods)) > 0:
|
|
||||||
|
|
||||||
write_string(f, "<methods>")
|
|
||||||
inc_tab()
|
|
||||||
|
|
||||||
for m in list(methods):
|
|
||||||
qualifiers = get_tag(m, "qualifiers")
|
|
||||||
|
|
||||||
write_string(f, '<method name="' + escape(m.attrib["name"]) + '" ' + qualifiers + ">")
|
|
||||||
inc_tab()
|
|
||||||
|
|
||||||
for a in list(m):
|
|
||||||
if a.tag == "return":
|
|
||||||
typ = get_tag(a, "type")
|
|
||||||
write_string(f, "<return" + typ + ">")
|
|
||||||
write_string(f, "</return>")
|
|
||||||
elif a.tag == "argument":
|
|
||||||
|
|
||||||
default = get_tag(a, "default")
|
|
||||||
|
|
||||||
write_string(
|
|
||||||
f,
|
|
||||||
'<argument index="'
|
|
||||||
+ a.attrib["index"]
|
|
||||||
+ '" name="'
|
|
||||||
+ escape(a.attrib["name"])
|
|
||||||
+ '" type="'
|
|
||||||
+ a.attrib["type"]
|
|
||||||
+ '"'
|
|
||||||
+ default
|
|
||||||
+ ">",
|
|
||||||
)
|
|
||||||
write_string(f, "</argument>")
|
|
||||||
|
|
||||||
write_string(f, "<description>")
|
|
||||||
if old_class != None:
|
|
||||||
old_method_descr = find_method_descr(old_class, m.attrib["name"])
|
|
||||||
if old_method_descr:
|
|
||||||
write_string(f, escape(escape(old_method_descr.strip())))
|
|
||||||
|
|
||||||
write_string(f, "</description>")
|
|
||||||
dec_tab()
|
|
||||||
write_string(f, "</method>")
|
|
||||||
dec_tab()
|
|
||||||
write_string(f, "</methods>")
|
|
||||||
|
|
||||||
signals = c.find("signals")
|
|
||||||
if signals != None and len(list(signals)) > 0:
|
|
||||||
|
|
||||||
write_string(f, "<signals>")
|
|
||||||
inc_tab()
|
|
||||||
|
|
||||||
for m in list(signals):
|
|
||||||
|
|
||||||
write_string(f, '<signal name="' + escape(m.attrib["name"]) + '">')
|
|
||||||
inc_tab()
|
|
||||||
|
|
||||||
for a in list(m):
|
|
||||||
if a.tag == "argument":
|
|
||||||
|
|
||||||
write_string(
|
|
||||||
f,
|
|
||||||
'<argument index="'
|
|
||||||
+ a.attrib["index"]
|
|
||||||
+ '" name="'
|
|
||||||
+ escape(a.attrib["name"])
|
|
||||||
+ '" type="'
|
|
||||||
+ a.attrib["type"]
|
|
||||||
+ '">',
|
|
||||||
)
|
|
||||||
write_string(f, "</argument>")
|
|
||||||
|
|
||||||
write_string(f, "<description>")
|
|
||||||
if old_class != None:
|
|
||||||
old_signal_descr = find_signal_descr(old_class, m.attrib["name"])
|
|
||||||
if old_signal_descr:
|
|
||||||
write_string(f, escape(old_signal_descr.strip()))
|
|
||||||
write_string(f, "</description>")
|
|
||||||
dec_tab()
|
|
||||||
write_string(f, "</signal>")
|
|
||||||
dec_tab()
|
|
||||||
write_string(f, "</signals>")
|
|
||||||
|
|
||||||
constants = c.find("constants")
|
|
||||||
if constants != None and len(list(constants)) > 0:
|
|
||||||
|
|
||||||
write_string(f, "<constants>")
|
|
||||||
inc_tab()
|
|
||||||
|
|
||||||
for m in list(constants):
|
|
||||||
|
|
||||||
write_string(f, '<constant name="' + escape(m.attrib["name"]) + '" value="' + m.attrib["value"] + '">')
|
|
||||||
old_constant_descr = find_constant_descr(old_class, m.attrib["name"])
|
|
||||||
if old_constant_descr:
|
|
||||||
write_string(f, escape(old_constant_descr.strip()))
|
|
||||||
write_string(f, "</constant>")
|
|
||||||
|
|
||||||
dec_tab()
|
|
||||||
write_string(f, "</constants>")
|
|
||||||
|
|
||||||
dec_tab()
|
|
||||||
write_string(f, "</class>")
|
|
||||||
|
|
||||||
|
|
||||||
for c in list(old_doc):
|
|
||||||
old_classes[c.attrib["name"]] = c
|
|
||||||
|
|
||||||
for c in list(new_doc):
|
|
||||||
write_class(c)
|
|
||||||
write_string(f, "</doc>\n")
|
|
|
@ -1042,6 +1042,8 @@ def make_footer(): # type: () -> str
|
||||||
".. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`\n"
|
".. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`\n"
|
||||||
".. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`\n"
|
".. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`\n"
|
||||||
".. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`\n"
|
".. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`\n"
|
||||||
|
".. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`\n"
|
||||||
|
".. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`\n"
|
||||||
)
|
)
|
||||||
# fmt: on
|
# fmt: on
|
||||||
|
|
||||||
|
|
|
@ -569,12 +569,15 @@ void DocData::generate(bool p_basic_types) {
|
||||||
method_list.sort();
|
method_list.sort();
|
||||||
Variant::get_constructor_list(Variant::Type(i), &method_list);
|
Variant::get_constructor_list(Variant::Type(i), &method_list);
|
||||||
|
|
||||||
for (int j = 0; j < Variant::OP_AND; j++) { //showing above 'and' is pretty confusing and there are a lot of variations
|
for (int j = 0; j < Variant::OP_AND; j++) { // Showing above 'and' is pretty confusing and there are a lot of variations.
|
||||||
|
|
||||||
for (int k = 0; k < Variant::VARIANT_MAX; k++) {
|
for (int k = 0; k < Variant::VARIANT_MAX; k++) {
|
||||||
Variant::Type rt = Variant::get_operator_return_type(Variant::Operator(j), Variant::Type(i), Variant::Type(k));
|
Variant::Type rt = Variant::get_operator_return_type(Variant::Operator(j), Variant::Type(i), Variant::Type(k));
|
||||||
if (rt != Variant::NIL) {
|
if (rt != Variant::NIL) { // Has operator.
|
||||||
//has operator
|
// Skip String % operator as it's registered separately for each Variant arg type,
|
||||||
|
// we'll add it manually below.
|
||||||
|
if (i == Variant::STRING && Variant::Operator(j) == Variant::OP_MODULE) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
MethodInfo mi;
|
MethodInfo mi;
|
||||||
mi.name = "operator " + Variant::get_operator_name(Variant::Operator(j));
|
mi.name = "operator " + Variant::get_operator_name(Variant::Operator(j));
|
||||||
mi.return_val.type = rt;
|
mi.return_val.type = rt;
|
||||||
|
@ -589,6 +592,21 @@ void DocData::generate(bool p_basic_types) {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if (i == Variant::STRING) {
|
||||||
|
// We skipped % operator above, and we register it manually once for Variant arg type here.
|
||||||
|
MethodInfo mi;
|
||||||
|
mi.name = "operator %";
|
||||||
|
mi.return_val.type = Variant::STRING;
|
||||||
|
|
||||||
|
PropertyInfo arg;
|
||||||
|
arg.name = "right";
|
||||||
|
arg.type = Variant::NIL;
|
||||||
|
arg.usage = PROPERTY_USAGE_NIL_IS_VARIANT;
|
||||||
|
mi.arguments.push_back(arg);
|
||||||
|
|
||||||
|
method_list.push_back(mi);
|
||||||
|
}
|
||||||
|
|
||||||
if (Variant::is_keyed(Variant::Type(i))) {
|
if (Variant::is_keyed(Variant::Type(i))) {
|
||||||
MethodInfo mi;
|
MethodInfo mi;
|
||||||
mi.name = "operator []";
|
mi.name = "operator []";
|
||||||
|
@ -1147,7 +1165,7 @@ Error DocData::save_classes(const String &p_default_path, const Map<String, Stri
|
||||||
qualifiers += " qualifiers=\"" + m.qualifiers.xml_escape() + "\"";
|
qualifiers += " qualifiers=\"" + m.qualifiers.xml_escape() + "\"";
|
||||||
}
|
}
|
||||||
|
|
||||||
_write_string(f, 2, "<method name=\"" + m.name + "\"" + qualifiers + ">");
|
_write_string(f, 2, "<method name=\"" + m.name.xml_escape() + "\"" + qualifiers + ">");
|
||||||
|
|
||||||
if (m.return_type != "") {
|
if (m.return_type != "") {
|
||||||
String enum_text;
|
String enum_text;
|
||||||
|
|
Loading…
Reference in a new issue