Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

GDScript(2.0) Documentation generation system #41095

Merged
merged 2 commits into from
Dec 2, 2020
Merged

GDScript(2.0) Documentation generation system #41095

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d0e7d9b
Documentation generation for GDScript
ThakeeNathees Nov 29, 2020
42bfa16
Refactor DocData into core and editor (DocTools) parts
ThakeeNathees Nov 29, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 126 additions & 0 deletions core/doc_data.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
/*************************************************************************/
/* doc_data.cpp */
/*************************************************************************/
/* This file is part of: */
/* GODOT ENGINE */
/* https://godotengine.org */
/*************************************************************************/
/* Copyright (c) 2007-2020 Juan Linietsky, Ariel Manzur. */
/* Copyright (c) 2014-2020 Godot Engine contributors (cf. AUTHORS.md). */
/* */
/* Permission is hereby granted, free of charge, to any person obtaining */
/* a copy of this software and associated documentation files (the */
/* "Software"), to deal in the Software without restriction, including */
/* without limitation the rights to use, copy, modify, merge, publish, */
/* distribute, sublicense, and/or sell copies of the Software, and to */
/* permit persons to whom the Software is furnished to do so, subject to */
/* the following conditions: */
/* */
/* The above copyright notice and this permission notice shall be */
/* included in all copies or substantial portions of the Software. */
/* */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*/
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
/*************************************************************************/

#include "doc_data.h"

void DocData::return_doc_from_retinfo(DocData::MethodDoc &p_method, const PropertyInfo &p_retinfo) {
if (p_retinfo.type == Variant::INT && p_retinfo.usage & PROPERTY_USAGE_CLASS_IS_ENUM) {
p_method.return_enum = p_retinfo.class_name;
if (p_method.return_enum.begins_with("_")) { //proxy class
p_method.return_enum = p_method.return_enum.substr(1, p_method.return_enum.length());
}
p_method.return_type = "int";
} else if (p_retinfo.class_name != StringName()) {
p_method.return_type = p_retinfo.class_name;
} else if (p_retinfo.type == Variant::ARRAY && p_retinfo.hint == PROPERTY_HINT_ARRAY_TYPE) {
p_method.return_type = p_retinfo.hint_string + "[]";
} else if (p_retinfo.hint == PROPERTY_HINT_RESOURCE_TYPE) {
p_method.return_type = p_retinfo.hint_string;
} else if (p_retinfo.type == Variant::NIL && p_retinfo.usage & PROPERTY_USAGE_NIL_IS_VARIANT) {
p_method.return_type = "Variant";
} else if (p_retinfo.type == Variant::NIL) {
p_method.return_type = "void";
} else {
p_method.return_type = Variant::get_type_name(p_retinfo.type);
}
}

void DocData::argument_doc_from_arginfo(DocData::ArgumentDoc &p_argument, const PropertyInfo &p_arginfo) {
p_argument.name = p_arginfo.name;

if (p_arginfo.type == Variant::INT && p_arginfo.usage & PROPERTY_USAGE_CLASS_IS_ENUM) {
p_argument.enumeration = p_arginfo.class_name;
if (p_argument.enumeration.begins_with("_")) { //proxy class
p_argument.enumeration = p_argument.enumeration.substr(1, p_argument.enumeration.length());
}
p_argument.type = "int";
} else if (p_arginfo.class_name != StringName()) {
p_argument.type = p_arginfo.class_name;
} else if (p_arginfo.type == Variant::ARRAY && p_arginfo.hint == PROPERTY_HINT_ARRAY_TYPE) {
p_argument.type = p_arginfo.hint_string + "[]";
} else if (p_arginfo.hint == PROPERTY_HINT_RESOURCE_TYPE) {
p_argument.type = p_arginfo.hint_string;
} else if (p_arginfo.type == Variant::NIL) {
// Parameters cannot be void, so PROPERTY_USAGE_NIL_IS_VARIANT is not necessary
p_argument.type = "Variant";
} else {
p_argument.type = Variant::get_type_name(p_arginfo.type);
}
}

void DocData::property_doc_from_scriptmemberinfo(DocData::PropertyDoc &p_property, const ScriptMemberInfo &p_memberinfo) {
p_property.name = p_memberinfo.propinfo.name;
p_property.description = p_memberinfo.doc_string;

if (p_memberinfo.propinfo.type == Variant::OBJECT) {
p_property.type = p_memberinfo.propinfo.class_name;
} else if (p_memberinfo.propinfo.type == Variant::NIL && p_memberinfo.propinfo.usage & PROPERTY_USAGE_NIL_IS_VARIANT) {
p_property.type = "Variant";
} else {
p_property.type = Variant::get_type_name(p_memberinfo.propinfo.type);
}

p_property.setter = p_memberinfo.setter;
p_property.getter = p_memberinfo.getter;

if (p_memberinfo.has_default_value && p_memberinfo.default_value.get_type() != Variant::OBJECT) {
p_property.default_value = p_memberinfo.default_value.get_construct_string().replace("\n", "");
}

p_property.overridden = false;
}

void DocData::method_doc_from_methodinfo(DocData::MethodDoc &p_method, const MethodInfo &p_methodinfo, const String &p_desc) {
p_method.name = p_methodinfo.name;
p_method.description = p_desc;

return_doc_from_retinfo(p_method, p_methodinfo.return_val);

for (int i = 0; i < p_methodinfo.arguments.size(); i++) {
DocData::ArgumentDoc argument;
argument_doc_from_arginfo(argument, p_methodinfo.arguments[i]);
int default_arg_index = i - (p_methodinfo.arguments.size() - p_methodinfo.default_arguments.size());
if (default_arg_index >= 0) {
Variant default_arg = p_methodinfo.default_arguments[default_arg_index];
argument.default_value = default_arg.get_construct_string();
}
p_method.arguments.push_back(argument);
}
}

void DocData::constant_doc_from_variant(DocData::ConstantDoc &p_const, const StringName &p_name, const Variant &p_value, const String &p_desc) {
p_const.name = p_name;
p_const.value = p_value;
p_const.description = p_desc;
}

void DocData::signal_doc_from_methodinfo(DocData::MethodDoc &p_signal, const MethodInfo &p_methodinfo, const String &p_desc) {
return method_doc_from_methodinfo(p_signal, p_methodinfo, p_desc);
}
39 changes: 25 additions & 14 deletions editor/doc_data.h → core/doc_data.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,16 @@
#include "core/templates/map.h"
#include "core/variant/variant.h"

struct ScriptMemberInfo {
PropertyInfo propinfo;
String doc_string;
StringName setter;
StringName getter;

bool has_default_value = false;
Variant default_value;
};

class DocData {
public:
struct ArgumentDoc {
Expand Down Expand Up @@ -87,6 +97,12 @@ class DocData {
}
};

struct EnumDoc {
String name = "@unnamed_enum";
String description;
Vector<DocData::ConstantDoc> values;
};

struct PropertyDoc {
String name;
String type;
Expand Down Expand Up @@ -115,27 +131,22 @@ class DocData {
Vector<MethodDoc> methods;
Vector<MethodDoc> signals;
Vector<ConstantDoc> constants;
Map<String, String> enums;
Vector<PropertyDoc> properties;
Vector<PropertyDoc> theme_properties;
bool is_script_doc = false;
String script_path;
bool operator<(const ClassDoc &p_class) const {
return name < p_class.name;
}
};

String version;

Map<String, ClassDoc> class_list;
Error _load(Ref<XMLParser> parser);

public:
void merge_from(const DocData &p_data);
void remove_from(const DocData &p_data);
void generate(bool p_basic_types = false);
Error load_classes(const String &p_dir);
static Error erase_classes(const String &p_dir);
Error save_classes(const String &p_default_path, const Map<String, String> &p_class_path);

Error load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size);
static void return_doc_from_retinfo(DocData::MethodDoc &p_method, const PropertyInfo &p_retinfo);
static void argument_doc_from_arginfo(DocData::ArgumentDoc &p_argument, const PropertyInfo &p_arginfo);
static void property_doc_from_scriptmemberinfo(DocData::PropertyDoc &p_property, const ScriptMemberInfo &p_memberinfo);
static void method_doc_from_methodinfo(DocData::MethodDoc &p_method, const MethodInfo &p_methodinfo, const String &p_desc);
static void constant_doc_from_variant(DocData::ConstantDoc &p_const, const StringName &p_name, const Variant &p_value, const String &p_desc);
static void signal_doc_from_methodinfo(DocData::MethodDoc &p_signal, const MethodInfo &p_methodinfo, const String &p_desc);
};

#endif // DOC_DATA_H
6 changes: 6 additions & 0 deletions core/object/script_language.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
#ifndef SCRIPT_LANGUAGE_H
#define SCRIPT_LANGUAGE_H

#include "core/doc_data.h"
#include "core/io/multiplayer_api.h"
#include "core/io/resource.h"
#include "core/templates/map.h"
Expand Down Expand Up @@ -145,6 +146,10 @@ class Script : public Resource {
virtual void set_source_code(const String &p_code) = 0;
virtual Error reload(bool p_keep_state = false) = 0;

#ifdef TOOLS_ENABLED
virtual const Vector<DocData::ClassDoc> &get_documentation() const = 0;
#endif // TOOLS_ENABLED

virtual bool has_method(const StringName &p_method) const = 0;
virtual MethodInfo get_method_info(const StringName &p_method) const = 0;

Expand Down Expand Up @@ -310,6 +315,7 @@ class ScriptLanguage {
virtual Script *create_script() const = 0;
virtual bool has_named_classes() const = 0;
virtual bool supports_builtin_mode() const = 0;
virtual bool supports_documentation() const { return false; }
virtual bool can_inherit_from_file() { return false; }
virtual int find_function(const String &p_function, const String &p_code) const = 0;
virtual String make_function(const String &p_class, const String &p_name, const PackedStringArray &p_args) const = 0;
Expand Down
3 changes: 2 additions & 1 deletion editor/connections_dialog.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
#include "connections_dialog.h"

#include "core/string/print_string.h"
#include "editor/doc_tools.h"
#include "editor_node.h"
#include "editor_scale.h"
#include "editor_settings.h"
Expand Down Expand Up @@ -997,7 +998,7 @@ void ConnectionsDock::update_tree() {
}

if (!found) {
DocData *dd = EditorHelp::get_doc_data();
DocTools *dd = EditorHelp::get_doc_data();
Map<String, DocData::ClassDoc>::Element *F = dd->class_list.find(base);
while (F && descr == String()) {
for (int i = 0; i < F->get().signals.size(); i++) {
Expand Down
Loading