1/**************************************************************************/
2/* gdscript_docgen.cpp */
3/**************************************************************************/
4/* This file is part of: */
5/* GODOT ENGINE */
6/* https://godotengine.org */
7/**************************************************************************/
8/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
9/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */
10/* */
11/* Permission is hereby granted, free of charge, to any person obtaining */
12/* a copy of this software and associated documentation files (the */
13/* "Software"), to deal in the Software without restriction, including */
14/* without limitation the rights to use, copy, modify, merge, publish, */
15/* distribute, sublicense, and/or sell copies of the Software, and to */
16/* permit persons to whom the Software is furnished to do so, subject to */
17/* the following conditions: */
18/* */
19/* The above copyright notice and this permission notice shall be */
20/* included in all copies or substantial portions of the Software. */
21/* */
22/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
23/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
24/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
25/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
26/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
27/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
28/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
29/**************************************************************************/
30
31#include "gdscript_docgen.h"
32
33#include "../gdscript.h"
34
35using GDP = GDScriptParser;
36using GDType = GDP::DataType;
37
38static String _get_script_path(const String &p_path) {
39 return p_path.trim_prefix("res://").quote();
40}
41
42static String _get_class_name(const GDP::ClassNode &p_class) {
43 const GDP::ClassNode *curr_class = &p_class;
44 if (!curr_class->identifier) { // All inner classes have an identifier, so this is the outer class.
45 return _get_script_path(curr_class->fqcn);
46 }
47
48 String full_name = curr_class->identifier->name;
49 while (curr_class->outer) {
50 curr_class = curr_class->outer;
51 if (!curr_class->identifier) { // All inner classes have an identifier, so this is the outer class.
52 return vformat("%s.%s", _get_script_path(curr_class->fqcn), full_name);
53 }
54 full_name = vformat("%s.%s", curr_class->identifier->name, full_name);
55 }
56 return full_name;
57}
58
59static void _doctype_from_gdtype(const GDType &p_gdtype, String &r_type, String &r_enum, bool p_is_return = false) {
60 if (!p_gdtype.is_hard_type()) {
61 r_type = "Variant";
62 return;
63 }
64 switch (p_gdtype.kind) {
65 case GDType::BUILTIN:
66 if (p_gdtype.builtin_type == Variant::NIL) {
67 r_type = p_is_return ? "void" : "null";
68 return;
69 }
70 if (p_gdtype.builtin_type == Variant::ARRAY && p_gdtype.has_container_element_type()) {
71 _doctype_from_gdtype(p_gdtype.get_container_element_type(), r_type, r_enum);
72 if (!r_enum.is_empty()) {
73 r_type = "int[]";
74 r_enum += "[]";
75 return;
76 }
77 if (!r_type.is_empty() && r_type != "Variant") {
78 r_type += "[]";
79 return;
80 }
81 }
82 r_type = Variant::get_type_name(p_gdtype.builtin_type);
83 return;
84 case GDType::NATIVE:
85 r_type = p_gdtype.native_type;
86 return;
87 case GDType::SCRIPT:
88 if (p_gdtype.script_type.is_valid()) {
89 if (p_gdtype.script_type->get_global_name() != StringName()) {
90 r_type = p_gdtype.script_type->get_global_name();
91 return;
92 }
93 if (!p_gdtype.script_type->get_path().is_empty()) {
94 r_type = _get_script_path(p_gdtype.script_type->get_path());
95 return;
96 }
97 }
98 if (!p_gdtype.script_path.is_empty()) {
99 r_type = _get_script_path(p_gdtype.script_path);
100 return;
101 }
102 r_type = "Object";
103 return;
104 case GDType::CLASS:
105 r_type = _get_class_name(*p_gdtype.class_type);
106 return;
107 case GDType::ENUM:
108 r_type = "int";
109 r_enum = String(p_gdtype.native_type).replace("::", ".");
110 if (r_enum.begins_with("res://")) {
111 r_enum = r_enum.trim_prefix("res://");
112 int dot_pos = r_enum.rfind(".");
113 if (dot_pos >= 0) {
114 r_enum = r_enum.left(dot_pos).quote() + r_enum.substr(dot_pos);
115 }
116 }
117 return;
118 case GDType::VARIANT:
119 case GDType::RESOLVING:
120 case GDType::UNRESOLVED:
121 r_type = "Variant";
122 return;
123 }
124}
125
126void GDScriptDocGen::generate_docs(GDScript *p_script, const GDP::ClassNode *p_class) {
127 p_script->_clear_doc();
128
129 DocData::ClassDoc &doc = p_script->doc;
130
131 doc.script_path = _get_script_path(p_script->get_script_path());
132 if (p_script->local_name == StringName()) {
133 doc.name = doc.script_path;
134 } else {
135 doc.name = p_script->local_name;
136 }
137
138 if (p_script->_owner) {
139 doc.name = p_script->_owner->doc.name + "." + doc.name;
140 doc.script_path = doc.script_path + "." + doc.name;
141 }
142
143 doc.is_script_doc = true;
144
145 if (p_script->base.is_valid() && p_script->base->is_valid()) {
146 if (!p_script->base->doc.name.is_empty()) {
147 doc.inherits = p_script->base->doc.name;
148 } else {
149 doc.inherits = p_script->base->get_instance_base_type();
150 }
151 } else if (p_script->native.is_valid()) {
152 doc.inherits = p_script->native->get_name();
153 }
154
155 doc.brief_description = p_class->doc_data.brief;
156 doc.description = p_class->doc_data.description;
157 for (const Pair<String, String> &p : p_class->doc_data.tutorials) {
158 DocData::TutorialDoc td;
159 td.title = p.first;
160 td.link = p.second;
161 doc.tutorials.append(td);
162 }
163 doc.is_deprecated = p_class->doc_data.is_deprecated;
164 doc.is_experimental = p_class->doc_data.is_experimental;
165
166 for (const GDP::ClassNode::Member &member : p_class->members) {
167 switch (member.type) {
168 case GDP::ClassNode::Member::CLASS: {
169 const GDP::ClassNode *inner_class = member.m_class;
170 const StringName &class_name = inner_class->identifier->name;
171
172 p_script->member_lines[class_name] = inner_class->start_line;
173
174 // Recursively generate inner class docs.
175 // Needs inner GDScripts to exist: previously generated in GDScriptCompiler::make_scripts().
176 GDScriptDocGen::generate_docs(*p_script->subclasses[class_name], inner_class);
177 } break;
178
179 case GDP::ClassNode::Member::CONSTANT: {
180 const GDP::ConstantNode *m_const = member.constant;
181 const StringName &const_name = member.constant->identifier->name;
182
183 p_script->member_lines[const_name] = m_const->start_line;
184
185 DocData::ConstantDoc const_doc;
186 DocData::constant_doc_from_variant(const_doc, const_name, m_const->initializer->reduced_value, m_const->doc_data.description);
187 const_doc.is_deprecated = m_const->doc_data.is_deprecated;
188 const_doc.is_experimental = m_const->doc_data.is_experimental;
189 doc.constants.push_back(const_doc);
190 } break;
191
192 case GDP::ClassNode::Member::FUNCTION: {
193 const GDP::FunctionNode *m_func = member.function;
194 const StringName &func_name = m_func->identifier->name;
195
196 p_script->member_lines[func_name] = m_func->start_line;
197
198 DocData::MethodDoc method_doc;
199 method_doc.name = func_name;
200 method_doc.description = m_func->doc_data.description;
201 method_doc.is_deprecated = m_func->doc_data.is_deprecated;
202 method_doc.is_experimental = m_func->doc_data.is_experimental;
203 method_doc.qualifiers = m_func->is_static ? "static" : "";
204
205 if (m_func->return_type) {
206 _doctype_from_gdtype(m_func->return_type->get_datatype(), method_doc.return_type, method_doc.return_enum, true);
207 } else if (!m_func->body->has_return) {
208 // If no `return` statement, then return type is `void`, not `Variant`.
209 method_doc.return_type = "void";
210 } else {
211 method_doc.return_type = "Variant";
212 }
213
214 for (const GDScriptParser::ParameterNode *p : m_func->parameters) {
215 DocData::ArgumentDoc arg_doc;
216 arg_doc.name = p->identifier->name;
217 _doctype_from_gdtype(p->get_datatype(), arg_doc.type, arg_doc.enumeration);
218 if (p->initializer != nullptr) {
219 if (p->initializer->is_constant) {
220 arg_doc.default_value = p->initializer->reduced_value.get_construct_string().replace("\n", "\\n");
221 } else {
222 arg_doc.default_value = "<unknown>";
223 }
224 }
225 method_doc.arguments.push_back(arg_doc);
226 }
227
228 doc.methods.push_back(method_doc);
229 } break;
230
231 case GDP::ClassNode::Member::SIGNAL: {
232 const GDP::SignalNode *m_signal = member.signal;
233 const StringName &signal_name = m_signal->identifier->name;
234
235 p_script->member_lines[signal_name] = m_signal->start_line;
236
237 DocData::MethodDoc signal_doc;
238 signal_doc.name = signal_name;
239 signal_doc.description = m_signal->doc_data.description;
240 signal_doc.is_deprecated = m_signal->doc_data.is_deprecated;
241 signal_doc.is_experimental = m_signal->doc_data.is_experimental;
242
243 for (const GDScriptParser::ParameterNode *p : m_signal->parameters) {
244 DocData::ArgumentDoc arg_doc;
245 arg_doc.name = p->identifier->name;
246 _doctype_from_gdtype(p->get_datatype(), arg_doc.type, arg_doc.enumeration);
247 signal_doc.arguments.push_back(arg_doc);
248 }
249
250 doc.signals.push_back(signal_doc);
251 } break;
252
253 case GDP::ClassNode::Member::VARIABLE: {
254 const GDP::VariableNode *m_var = member.variable;
255 const StringName &var_name = m_var->identifier->name;
256
257 p_script->member_lines[var_name] = m_var->start_line;
258
259 DocData::PropertyDoc prop_doc;
260 prop_doc.name = var_name;
261 prop_doc.description = m_var->doc_data.description;
262 prop_doc.is_deprecated = m_var->doc_data.is_deprecated;
263 prop_doc.is_experimental = m_var->doc_data.is_experimental;
264 _doctype_from_gdtype(m_var->get_datatype(), prop_doc.type, prop_doc.enumeration);
265
266 switch (m_var->property) {
267 case GDP::VariableNode::PROP_NONE:
268 break;
269 case GDP::VariableNode::PROP_INLINE:
270 if (m_var->setter != nullptr) {
271 prop_doc.setter = m_var->setter->identifier->name;
272 }
273 if (m_var->getter != nullptr) {
274 prop_doc.getter = m_var->getter->identifier->name;
275 }
276 break;
277 case GDP::VariableNode::PROP_SETGET:
278 if (m_var->setter_pointer != nullptr) {
279 prop_doc.setter = m_var->setter_pointer->name;
280 }
281 if (m_var->getter_pointer != nullptr) {
282 prop_doc.getter = m_var->getter_pointer->name;
283 }
284 break;
285 }
286
287 if (m_var->initializer) {
288 if (m_var->initializer->is_constant) {
289 prop_doc.default_value = m_var->initializer->reduced_value.get_construct_string().replace("\n", "\\n");
290 } else {
291 prop_doc.default_value = "<unknown>";
292 }
293 }
294
295 prop_doc.overridden = false;
296
297 doc.properties.push_back(prop_doc);
298 } break;
299
300 case GDP::ClassNode::Member::ENUM: {
301 const GDP::EnumNode *m_enum = member.m_enum;
302 StringName name = m_enum->identifier->name;
303
304 p_script->member_lines[name] = m_enum->start_line;
305
306 DocData::EnumDoc enum_doc;
307 enum_doc.description = m_enum->doc_data.description;
308 enum_doc.is_deprecated = m_enum->doc_data.is_deprecated;
309 enum_doc.is_experimental = m_enum->doc_data.is_experimental;
310 doc.enums[name] = enum_doc;
311
312 for (const GDP::EnumNode::Value &val : m_enum->values) {
313 DocData::ConstantDoc const_doc;
314 const_doc.name = val.identifier->name;
315 const_doc.value = String(Variant(val.value));
316 const_doc.is_value_valid = true;
317 const_doc.enumeration = name;
318 const_doc.description = val.doc_data.description;
319 const_doc.is_deprecated = val.doc_data.is_deprecated;
320 const_doc.is_experimental = val.doc_data.is_experimental;
321
322 doc.constants.push_back(const_doc);
323 }
324
325 } break;
326
327 case GDP::ClassNode::Member::ENUM_VALUE: {
328 const GDP::EnumNode::Value &m_enum_val = member.enum_value;
329 const StringName &name = m_enum_val.identifier->name;
330
331 p_script->member_lines[name] = m_enum_val.identifier->start_line;
332
333 DocData::ConstantDoc const_doc;
334 DocData::constant_doc_from_variant(const_doc, name, m_enum_val.value, m_enum_val.doc_data.description);
335 const_doc.enumeration = "@unnamed_enums";
336 const_doc.is_deprecated = m_enum_val.doc_data.is_deprecated;
337 const_doc.is_experimental = m_enum_val.doc_data.is_experimental;
338 doc.constants.push_back(const_doc);
339 } break;
340
341 default:
342 break;
343 }
344 }
345
346 // Add doc to the outer-most class.
347 p_script->_add_doc(doc);
348}
349