godotengine/godot
1
0
Fork 0
mirror of https://github.com/godotengine/godot.git synced 2025-11-07 12:30:27 +00:00
Code Releases Wiki Activity

Documentation generation for GDScript

Browse Source 
- ClassDoc added to GDScript and property reflection data were extracted
from parse tree

- GDScript comments are collected from tokenizer for documentation and
applied to the ClassDoc by the GDScript compiler

- private docs were excluded (name with underscore prefix and doesn't
have any doc comments)

- default values (of non exported vars), arguments are extraced from the
parser

- Integrated with GDScript 2.0 and new enums were added.

- merge conflicts fixed
This commit is contained in:
Thakee Nathees
2020-11-29 08:07:57 +05:30
parent ef2d1f6d19
commit d0e7d9b62f
21 changed files with 1036 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

214
editor/editor_help.cpp
View File

@@ -388,7 +388,7 @@ void EditorHelp::_update_doc() {
}
// Descendents
if (ClassDB::class_exists(cd.name)) {
if (cd.is_script_doc || ClassDB::class_exists(cd.name)) {
bool found = false;
bool prev = false;
@@ -494,7 +494,19 @@ void EditorHelp::_update_doc() {
Set<String> skip_methods;
bool property_descr = false;
if (cd.properties.size()) {
bool has_properties = cd.properties.size() != 0;
if (cd.is_script_doc) {
has_properties = false;
for (int i = 0; i < cd.properties.size(); i++) {
if (cd.properties[i].name.begins_with("_") && cd.properties[i].description.empty()) {
continue;
}
has_properties = true;
break;
}
}
if (has_properties) {
section_line.push_back(Pair<String, int>(TTR("Properties"), class_desc->get_line_count() - 2));
class_desc->push_color(title_color);
class_desc->push_font(doc_title_font);
@@ -509,6 +521,10 @@ void EditorHelp::_update_doc() {
class_desc->set_table_column_expand(1, true);
for (int i = 0; i < cd.properties.size(); i++) {
// Ignore undocumented private.
if (cd.properties[i].name.begins_with("_") && cd.properties[i].description.empty()) {
continue;
}
property_line[cd.properties[i].name] = class_desc->get_line_count() - 2; //gets overridden if description
class_desc->push_cell();
@@ -565,6 +581,32 @@ void EditorHelp::_update_doc() {
class_desc->pop();
}
if (cd.is_script_doc && (cd.properties[i].setter != "" || cd.properties[i].getter != "")) {
class_desc->push_color(symbol_color);
class_desc->add_text(" [" + TTR("property:") + " ");
class_desc->pop(); // color
if (cd.properties[i].setter != "") {
class_desc->push_color(value_color);
class_desc->add_text("setter");
class_desc->pop(); // color
}
if (cd.properties[i].getter != "") {
if (cd.properties[i].setter != "") {
class_desc->push_color(symbol_color);
class_desc->add_text(", ");
class_desc->pop(); // color
}
class_desc->push_color(value_color);
class_desc->add_text("getter");
class_desc->pop(); // color
}
class_desc->push_color(symbol_color);
class_desc->add_text("]");
class_desc->pop(); // color
}
class_desc->pop();
class_desc->pop();
@@ -590,6 +632,10 @@ void EditorHelp::_update_doc() {
continue;
}
}
// Ignore undocumented private.
if (cd.methods[i].name.begins_with("_") && cd.methods[i].description.empty()) {
continue;
}
methods.push_back(cd.methods[i]);
}
@@ -802,13 +848,17 @@ void EditorHelp::_update_doc() {
Vector<DocData::ConstantDoc> constants;
for (int i = 0; i < cd.constants.size(); i++) {
if (cd.constants[i].enumeration != String()) {
if (!cd.constants[i].enumeration.empty()) {
if (!enums.has(cd.constants[i].enumeration)) {
enums[cd.constants[i].enumeration] = Vector<DocData::ConstantDoc>();
}
enums[cd.constants[i].enumeration].push_back(cd.constants[i]);
} else {
// Ignore undocumented private.
if (cd.constants[i].name.begins_with("_") && cd.constants[i].description.empty()) {
continue;
}
constants.push_back(cd.constants[i]);
}
}
@@ -848,6 +898,19 @@ void EditorHelp::_update_doc() {
class_desc->add_newline();
class_desc->add_newline();
// Enum description.
if (e != "@unnamed_enums" && cd.enums.has(e)) {
class_desc->push_color(text_color);
class_desc->push_font(doc_font);
class_desc->push_indent(1);
_add_text(cd.enums[e]);
class_desc->pop();
class_desc->pop();
class_desc->pop();
class_desc->add_newline();
class_desc->add_newline();
}
class_desc->push_indent(1);
Vector<DocData::ConstantDoc> enum_list = E->get();
@@ -1018,60 +1081,89 @@ void EditorHelp::_update_doc() {
class_desc->pop(); // color
}
if (cd.is_script_doc && (cd.properties[i].setter != "" || cd.properties[i].getter != "")) {
class_desc->push_color(symbol_color);
class_desc->add_text(" [" + TTR("property:") + " ");
class_desc->pop(); // color
if (cd.properties[i].setter != "") {
class_desc->push_color(value_color);
class_desc->add_text("setter");
class_desc->pop(); // color
}
if (cd.properties[i].getter != "") {
if (cd.properties[i].setter != "") {
class_desc->push_color(symbol_color);
class_desc->add_text(", ");
class_desc->pop(); // color
}
class_desc->push_color(value_color);
class_desc->add_text("getter");
class_desc->pop(); // color
}
class_desc->push_color(symbol_color);
class_desc->add_text("]");
class_desc->pop(); // color
}
class_desc->pop(); // font
class_desc->pop(); // cell
Map<String, DocData::MethodDoc> method_map;
for (int j = 0; j < methods.size(); j++) {
method_map[methods[j].name] = methods[j];
}
if (cd.properties[i].setter != "") {
class_desc->push_cell();
class_desc->pop(); // cell
class_desc->push_cell();
class_desc->push_font(doc_code_font);
class_desc->push_color(text_color);
if (method_map[cd.properties[i].setter].arguments.size() > 1) {
// Setters with additional arguments are exposed in the method list, so we link them here for quick access.
class_desc->push_meta("@method " + cd.properties[i].setter);
class_desc->add_text(cd.properties[i].setter + TTR("(value)"));
class_desc->pop();
} else {
class_desc->add_text(cd.properties[i].setter + TTR("(value)"));
// Script doc doesn't have setter, getter.
if (!cd.is_script_doc) {
Map<String, DocData::MethodDoc> method_map;
for (int j = 0; j < methods.size(); j++) {
method_map[methods[j].name] = methods[j];
}
class_desc->pop(); // color
class_desc->push_color(comment_color);
class_desc->add_text(" setter");
class_desc->pop(); // color
class_desc->pop(); // font
class_desc->pop(); // cell
method_line[cd.properties[i].setter] = property_line[cd.properties[i].name];
}
if (cd.properties[i].getter != "") {
class_desc->push_cell();
class_desc->pop(); // cell
if (cd.properties[i].setter != "") {
class_desc->push_cell();
class_desc->pop(); // cell
class_desc->push_cell();
class_desc->push_font(doc_code_font);
class_desc->push_color(text_color);
if (method_map[cd.properties[i].getter].arguments.size() > 0) {
// Getters with additional arguments are exposed in the method list, so we link them here for quick access.
class_desc->push_meta("@method " + cd.properties[i].getter);
class_desc->add_text(cd.properties[i].getter + "()");
class_desc->pop();
} else {
class_desc->add_text(cd.properties[i].getter + "()");
class_desc->push_cell();
class_desc->push_font(doc_code_font);
class_desc->push_color(text_color);
if (method_map[cd.properties[i].setter].arguments.size() > 1) {
// Setters with additional arguments are exposed in the method list, so we link them here for quick access.
class_desc->push_meta("@method " + cd.properties[i].setter);
class_desc->add_text(cd.properties[i].setter + TTR("(value)"));
class_desc->pop();
} else {
class_desc->add_text(cd.properties[i].setter + TTR("(value)"));
}
class_desc->pop(); // color
class_desc->push_color(comment_color);
class_desc->add_text(" setter");
class_desc->pop(); // color
class_desc->pop(); // font
class_desc->pop(); // cell
method_line[cd.properties[i].setter] = property_line[cd.properties[i].name];
}
if (cd.properties[i].getter != "") {
class_desc->push_cell();
class_desc->pop(); // cell
class_desc->push_cell();
class_desc->push_font(doc_code_font);
class_desc->push_color(text_color);
if (method_map[cd.properties[i].getter].arguments.size() > 0) {
// Getters with additional arguments are exposed in the method list, so we link them here for quick access.
class_desc->push_meta("@method " + cd.properties[i].getter);
class_desc->add_text(cd.properties[i].getter + "()");
class_desc->pop();
} else {
class_desc->add_text(cd.properties[i].getter + "()");
}
class_desc->pop(); //color
class_desc->push_color(comment_color);
class_desc->add_text(" getter");
class_desc->pop(); //color
class_desc->pop(); //font
class_desc->pop(); //cell
method_line[cd.properties[i].getter] = property_line[cd.properties[i].name];
}
class_desc->pop(); //color
class_desc->push_color(comment_color);
class_desc->add_text(" getter");
class_desc->pop(); //color
class_desc->pop(); //font
class_desc->pop(); //cell
method_line[cd.properties[i].getter] = property_line[cd.properties[i].name];
}
class_desc->pop(); // table
@@ -1082,13 +1174,17 @@ void EditorHelp::_update_doc() {
class_desc->push_color(text_color);
class_desc->push_font(doc_font);
class_desc->push_indent(1);
if (cd.properties[i].description.strip_edges() != String()) {
if (!cd.properties[i].description.strip_edges().empty()) {
_add_text(DTR(cd.properties[i].description));
} else {
class_desc->add_image(get_theme_icon("Error", "EditorIcons"));
class_desc->add_text(" ");
class_desc->push_color(comment_color);
class_desc->append_bbcode(TTR("There is currently no description for this property. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
if (cd.is_script_doc) {
class_desc->append_bbcode(TTR("There is currently no description for this property."));
} else {
class_desc->append_bbcode(TTR("There is currently no description for this property. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
}
class_desc->pop();
}
class_desc->pop();
@@ -1133,13 +1229,17 @@ 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].description.strip_edges() != String()) {
if (!methods_filtered[i].description.strip_edges().empty()) {
_add_text(DTR(methods_filtered[i].description));
} else {
class_desc->add_image(get_theme_icon("Error", "EditorIcons"));
class_desc->add_text(" ");
class_desc->push_color(comment_color);
class_desc->append_bbcode(TTR("There is currently no description for this method. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
if (cd.is_script_doc) {
class_desc->append_bbcode(TTR("There is currently no description for this method."));
} else {
class_desc->append_bbcode(TTR("There is currently no description for this method. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
}
class_desc->pop();
}
@@ -1549,6 +1649,12 @@ void EditorHelp::go_to_class(const String &p_class, int p_scroll) {
_goto_desc(p_class, p_scroll);
}
void EditorHelp::update_doc() {
ERR_FAIL_COND(!doc->class_list.has(edited_class));
ERR_FAIL_COND(!doc->class_list[edited_class].is_script_doc);
_update_doc();
}
Vector<Pair<String, int>> EditorHelp::get_sections() {
Vector<Pair<String, int>> sections;