Skip to content

Commit

Permalink
GDScript: Add @deprecated and @experimental doc comment tags
Browse files Browse the repository at this point in the history
  • Loading branch information
@dalexeev
dalexeev committed Jul 8, 2023
1 parent c3b0a92 commit c1b4505
Show file tree
Hide file tree
Showing 5 changed files with 211 additions and 99 deletions.
44 changes: 40 additions & 4 deletions core/doc_data.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -532,6 +532,42 @@ class DocData {
}
};

struct EnumDoc {
String description;
bool is_deprecated = false;
bool is_experimental = false;
static EnumDoc from_dict(const Dictionary &p_dict) {
EnumDoc doc;

if (p_dict.has("description")) {
doc.description = p_dict["description"];
}

if (p_dict.has("is_deprecated")) {
doc.is_deprecated = p_dict["is_deprecated"];
}

if (p_dict.has("is_experimental")) {
doc.is_experimental = p_dict["is_experimental"];
}

return doc;
}
static Dictionary to_dict(const EnumDoc &p_doc) {
Dictionary dict;

if (!p_doc.description.is_empty()) {
dict["description"] = p_doc.description;
}

dict["is_deprecated"] = p_doc.is_deprecated;

dict["is_experimental"] = p_doc.is_experimental;

return dict;
}
};

struct ClassDoc {
String name;
String inherits;
Expand All @@ -543,7 +579,7 @@ class DocData {
Vector<MethodDoc> operators;
Vector<MethodDoc> signals;
Vector<ConstantDoc> constants;
HashMap<String, String> enums;
HashMap<String, EnumDoc> enums;
Vector<PropertyDoc> properties;
Vector<MethodDoc> annotations;
Vector<ThemeItemDoc> theme_properties;
Expand Down Expand Up @@ -626,7 +662,7 @@ class DocData {
enums = p_dict["enums"];
}
for (int i = 0; i < enums.size(); i++) {
doc.enums[enums.get_key_at_index(i)] = enums.get_value_at_index(i);
doc.enums[enums.get_key_at_index(i)] = EnumDoc::from_dict(enums.get_value_at_index(i));
}

Array properties;
Expand Down Expand Up @@ -740,8 +776,8 @@ class DocData {

if (!p_doc.enums.is_empty()) {
Dictionary enums;
for (const KeyValue<String, String> &E : p_doc.enums) {
enums[E.key] = E.value;
for (const KeyValue<String, EnumDoc> &E : p_doc.enums) {
enums[E.key] = EnumDoc::to_dict(E.value);
}
dict["enums"] = enums;
}
Expand Down
29 changes: 23 additions & 6 deletions editor/editor_help.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1037,6 +1037,7 @@ void EditorHelp::_update_doc() {
if (cd.properties[i].is_deprecated) {
DEPRECATED_DOC_TAG;
}

if (cd.properties[i].is_experimental) {
EXPERIMENTAL_DOC_TAG;
}
Expand Down Expand Up @@ -1281,6 +1282,7 @@ void EditorHelp::_update_doc() {
if (cd.signals[i].is_deprecated) {
DEPRECATED_DOC_TAG;
}

if (cd.signals[i].is_experimental) {
EXPERIMENTAL_DOC_TAG;
}
Expand Down Expand Up @@ -1341,6 +1343,7 @@ void EditorHelp::_update_doc() {
enum_line[E.key] = class_desc->get_paragraph_count() - 2;

_push_code_font();

class_desc->push_color(theme_cache.title_color);
if (E.value.size() && E.value[0].is_bitfield) {
class_desc->add_text("flags ");
Expand All @@ -1357,21 +1360,32 @@ void EditorHelp::_update_doc() {
class_desc->push_color(theme_cache.headline_color);
class_desc->add_text(e);
class_desc->pop();
_pop_code_font();

class_desc->push_color(theme_cache.symbol_color);
class_desc->add_text(":");
class_desc->pop();

if (cd.enums.has(e)) {
if (cd.enums[e].is_deprecated) {
DEPRECATED_DOC_TAG;
}

if (cd.enums[e].is_experimental) {
EXPERIMENTAL_DOC_TAG;
}
}

_pop_code_font();

class_desc->add_newline();
class_desc->add_newline();

// Enum description.
if (e != "@unnamed_enums" && cd.enums.has(e) && !cd.enums[e].strip_edges().is_empty()) {
if (e != "@unnamed_enums" && cd.enums.has(e) && !cd.enums[e].description.strip_edges().is_empty()) {
class_desc->push_color(theme_cache.text_color);
_push_normal_font();
class_desc->push_indent(1);
_add_text(cd.enums[e]);
_add_text(cd.enums[e].description);
class_desc->pop();
_pop_normal_font();
class_desc->pop();
Expand All @@ -1395,6 +1409,7 @@ void EditorHelp::_update_doc() {
constant_line[enum_list[i].name] = class_desc->get_paragraph_count() - 2;

_push_code_font();

_add_bulletpoint();
class_desc->push_color(theme_cache.headline_color);
_add_text(enum_list[i].name);
Expand All @@ -1405,7 +1420,6 @@ void EditorHelp::_update_doc() {
class_desc->push_color(theme_cache.value_color);
_add_text(_fix_constant(enum_list[i].value));
class_desc->pop();
_pop_code_font();

if (enum_list[i].is_deprecated) {
DEPRECATED_DOC_TAG;
Expand All @@ -1415,6 +1429,8 @@ void EditorHelp::_update_doc() {
EXPERIMENTAL_DOC_TAG;
}

_pop_code_font();

class_desc->add_newline();

if (!enum_list[i].description.strip_edges().is_empty()) {
Expand Down Expand Up @@ -1481,8 +1497,6 @@ void EditorHelp::_update_doc() {
_add_text(_fix_constant(constants[i].value));
class_desc->pop();

_pop_code_font();

if (constants[i].is_deprecated) {
DEPRECATED_DOC_TAG;
}
Expand All @@ -1491,6 +1505,8 @@ void EditorHelp::_update_doc() {
EXPERIMENTAL_DOC_TAG;
}

_pop_code_font();

class_desc->add_newline();

if (!constants[i].description.strip_edges().is_empty()) {
Expand Down Expand Up @@ -1670,6 +1686,7 @@ void EditorHelp::_update_doc() {
if (cd.properties[i].is_deprecated) {
DEPRECATED_DOC_TAG;
}

if (cd.properties[i].is_experimental) {
EXPERIMENTAL_DOC_TAG;
}
Expand Down
44 changes: 31 additions & 13 deletions modules/gdscript/editor/gdscript_docgen.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,14 +101,16 @@ void GDScriptDocGen::generate_docs(GDScript *p_script, const GDP::ClassNode *p_c
doc.inherits = p_script->native->get_name();
}

doc.brief_description = p_class->doc_brief_description;
doc.description = p_class->doc_description;
for (const Pair<String, String> &p : p_class->doc_tutorials) {
doc.brief_description = p_class->doc_data.brief;
doc.description = p_class->doc_data.description;
for (const Pair<String, String> &p : p_class->doc_data.tutorials) {
DocData::TutorialDoc td;
td.title = p.first;
td.link = p.second;
doc.tutorials.append(td);
}
doc.is_deprecated = p_class->doc_data.is_deprecated;
doc.is_experimental = p_class->doc_data.is_experimental;

for (const GDP::ClassNode::Member &member : p_class->members) {
switch (member.type) {
Expand All @@ -130,7 +132,9 @@ void GDScriptDocGen::generate_docs(GDScript *p_script, const GDP::ClassNode *p_c
p_script->member_lines[const_name] = m_const->start_line;

DocData::ConstantDoc const_doc;
DocData::constant_doc_from_variant(const_doc, const_name, m_const->initializer->reduced_value, m_const->doc_description);
DocData::constant_doc_from_variant(const_doc, const_name, m_const->initializer->reduced_value, m_const->doc_data.description);
const_doc.is_deprecated = m_const->doc_data.is_deprecated;
const_doc.is_experimental = m_const->doc_data.is_experimental;
doc.constants.push_back(const_doc);
} break;

Expand All @@ -153,7 +157,9 @@ void GDScriptDocGen::generate_docs(GDScript *p_script, const GDP::ClassNode *p_c
}

DocData::MethodDoc method_doc;
DocData::method_doc_from_methodinfo(method_doc, mi, m_func->doc_description);
DocData::method_doc_from_methodinfo(method_doc, mi, m_func->doc_data.description);
method_doc.is_deprecated = m_func->doc_data.is_deprecated;
method_doc.is_experimental = m_func->doc_data.is_experimental;
doc.methods.push_back(method_doc);
} break;

Expand All @@ -172,7 +178,9 @@ void GDScriptDocGen::generate_docs(GDScript *p_script, const GDP::ClassNode *p_c
}

DocData::MethodDoc signal_doc;
DocData::signal_doc_from_methodinfo(signal_doc, mi, m_signal->doc_description);
DocData::signal_doc_from_methodinfo(signal_doc, mi, m_signal->doc_data.description);
signal_doc.is_deprecated = m_signal->doc_data.is_deprecated;
signal_doc.is_experimental = m_signal->doc_data.is_experimental;
doc.signals.push_back(signal_doc);
} break;

Expand All @@ -185,7 +193,9 @@ void GDScriptDocGen::generate_docs(GDScript *p_script, const GDP::ClassNode *p_c
DocData::PropertyDoc prop_doc;

prop_doc.name = var_name;
prop_doc.description = m_var->doc_description;
prop_doc.description = m_var->doc_data.description;
prop_doc.is_deprecated = m_var->doc_data.is_deprecated;
prop_doc.is_experimental = m_var->doc_data.is_experimental;

GDType dt = m_var->get_datatype();
switch (dt.kind) {
Expand Down Expand Up @@ -236,15 +246,21 @@ void GDScriptDocGen::generate_docs(GDScript *p_script, const GDP::ClassNode *p_c

p_script->member_lines[name] = m_enum->start_line;

doc.enums[name] = m_enum->doc_description;
DocData::EnumDoc enum_doc;
enum_doc.description = m_enum->doc_data.description;
enum_doc.is_deprecated = m_enum->doc_data.is_deprecated;
enum_doc.is_experimental = m_enum->doc_data.is_experimental;
doc.enums[name] = enum_doc;

for (const GDP::EnumNode::Value &val : m_enum->values) {
DocData::ConstantDoc const_doc;
const_doc.name = val.identifier->name;
const_doc.value = String(Variant(val.value));
const_doc.is_value_valid = true;
const_doc.description = val.doc_description;
const_doc.enumeration = name;
const_doc.description = val.doc_data.description;
const_doc.is_deprecated = val.doc_data.is_deprecated;
const_doc.is_experimental = val.doc_data.is_experimental;

doc.constants.push_back(const_doc);
}
Expand All @@ -257,10 +273,12 @@ void GDScriptDocGen::generate_docs(GDScript *p_script, const GDP::ClassNode *p_c

p_script->member_lines[name] = m_enum_val.identifier->start_line;

DocData::ConstantDoc constant_doc;
constant_doc.enumeration = "@unnamed_enums";
DocData::constant_doc_from_variant(constant_doc, name, m_enum_val.value, m_enum_val.doc_description);
doc.constants.push_back(constant_doc);
DocData::ConstantDoc const_doc;
DocData::constant_doc_from_variant(const_doc, name, m_enum_val.value, m_enum_val.doc_data.description);
const_doc.enumeration = "@unnamed_enums";
const_doc.is_deprecated = m_enum_val.doc_data.is_deprecated;
const_doc.is_experimental = m_enum_val.doc_data.is_experimental;
doc.constants.push_back(const_doc);
} break;
case GDP::ClassNode::Member::GROUP:
case GDP::ClassNode::Member::UNDEFINED:
Expand Down
Loading

0 comments on commit c1b4505

Please sign in to comment.