noahbackus/godot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

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

Browse Source
This commit is contained in:
Rémi Verschelde
2022-07-06 15:31:19 +02:00
committed by GitHub
parent ea61cd3b32 a9098e6147
commit 635d447a69
19 changed files with 462 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
doc/class.xsd
View File

@@ -163,6 +163,42 @@
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="annotations" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="annotation" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="return" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:sequence />
</xs:sequence>
<xs:attribute type="xs:string" name="type" />
<xs:attribute type="xs:string" name="enum" use="optional" />
</xs:complexType>
</xs:element>
<xs:element name="argument" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:sequence />
</xs:sequence>
<xs:attribute type="xs:byte" name="index" />
<xs:attribute type="xs:string" name="name" />
<xs:attribute type="xs:string" name="type" />
<xs:attribute type="xs:string" name="enum" use="optional" />
<xs:attribute type="xs:string" name="default" use="optional" />
</xs:complexType>
</xs:element>
<xs:element type="xs:string" name="description" />
</xs:sequence>
<xs:attribute type="xs:string" name="name" use="optional" />
<xs:attribute type="xs:string" name="qualifiers" use="optional" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="theme_items" minOccurs="0">
<xs:complexType>
<xs:sequence>

9
doc/classes/ScriptLanguageExtension.xml
View File

@@ -174,6 +174,11 @@
<description>
</description>
</method>
<method name="_get_public_annotations" qualifiers="virtual const">
<return type="Dictionary[]" />
<description>
</description>
</method>
<method name="_get_public_constants" qualifiers="virtual const">
<return type="Dictionary" />
<description>
@@ -378,7 +383,9 @@
</constant>
<constant name="LOOKUP_RESULT_CLASS_TBD_GLOBALSCOPE" value="7" enum="LookupResultType">
</constant>
<constant name="LOOKUP_RESULT_MAX" value="8" enum="LookupResultType">
<constant name="LOOKUP_RESULT_CLASS_ANNOTATION" value="8" enum="LookupResultType">
</constant>
<constant name="LOOKUP_RESULT_MAX" value="9" enum="LookupResultType">
</constant>
<constant name="LOCATION_LOCAL" value="0" enum="CodeCompletionLocation">
The option is local to the location of the code completion query - e.g. a local variable.

48
doc/tools/make_rst.py
View File

@@ -36,6 +36,7 @@ BASE_STRINGS = [
"Signals",
"Enumerations",
"Constants",
"Annotations",
"Property Descriptions",
"Constructor Descriptions",
"Method Descriptions",
@@ -157,6 +158,7 @@ class ClassDef:
self.methods = OrderedDict() # type: OrderedDict[str, List[MethodDef]]
self.operators = OrderedDict() # type: OrderedDict[str, List[MethodDef]]
self.signals = OrderedDict() # type: OrderedDict[str, SignalDef]
self.annotations = OrderedDict() # type: OrderedDict[str, List[MethodDef]]
self.theme_items = OrderedDict() # type: OrderedDict[str, ThemeItemDef]
self.inherits = None # type: Optional[str]
self.brief_description = None # type: Optional[str]
@@ -326,6 +328,27 @@ class State:
enum_def.values[constant_name] = constant_def
annotations = class_root.find("annotations")
if annotations is not None:
for annotation in annotations:
assert annotation.tag == "annotation"
annotation_name = annotation.attrib["name"]
qualifiers = annotation.get("qualifiers")
params = parse_arguments(annotation)
desc_element = annotation.find("description")
annotation_desc = None
if desc_element is not None:
annotation_desc = desc_element.text
annotation_def = MethodDef(annotation_name, return_type, params, annotation_desc, qualifiers)
if annotation_name not in class_def.annotations:
class_def.annotations[annotation_name] = []
class_def.annotations[annotation_name].append(annotation_def)
signals = class_root.find("signals")
if signals is not None:
for signal in signals:
@@ -739,6 +762,26 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S
f.write("\n\n")
if len(class_def.annotations) > 0:
f.write(make_heading("Annotations", "-"))
index = 0
for method_list in class_def.annotations.values():
for i, m in enumerate(method_list):
if index != 0:
f.write("----\n\n")
if i == 0:
f.write(".. _class_{}_annotation_{}:\n\n".format(class_name, m.name.strip("@")))
ret_type, signature = make_method_signature(class_def, m, "", state)
f.write("- {} {}\n\n".format(ret_type, signature))
if m.description is not None and m.description.strip() != "":
f.write(rstize_text(m.description.strip(), state) + "\n\n")
index += 1
# Property descriptions
if any(not p.overrides for p in class_def.properties.values()) > 0:
f.write(make_heading("Property Descriptions", "-"))
@@ -1072,6 +1115,11 @@ def rstize_text(text, state): # type: (str, State) -> str
print_error('{}.xml: Unresolved signal "{}".'.format(state.current_class, param), state)
ref_type = "_signal"
elif cmd.startswith("annotation"):
if method_param not in class_def.annotations:
print_error('{}.xml: Unresolved annotation "{}".'.format(state.current_class, param), state)
ref_type = "_annotation"
elif cmd.startswith("constant"):
found = False