GDExtension: Add Engine method to allow registering class reference data

This can be used from a GDExtension's init callback to add zlib-compressed class reference XML data for use in the editor help.
godotengine · Jun 29, 2023 · 4b676a0 · 4b676a0
1 parent 16dd4e5
commit 4b676a0
Show file tree

Hide file tree

Showing 8 changed files with 51 additions and 3 deletions.
diff --git a/core/config/engine.cpp b/core/config/engine.cpp
@@ -292,6 +292,17 @@ void Engine::get_singletons(List<Singleton> *p_singletons) {
 	}
 }
 
+void Engine::add_extension_class_doc(PackedByteArray p_compressed_data, int p_uncompressed_size) {
+	ExtensionClassDoc doc;
+	doc.compressed_data = p_compressed_data;
+	doc.uncompressed_size = p_uncompressed_size;
+	extensions_class_doc.push_back(doc);
+}
+
+const Vector<Engine::ExtensionClassDoc> &Engine::get_extensions_class_doc() const {
+	return extensions_class_doc;
+}
+
 String Engine::get_write_movie_path() const {
 	return write_movie_path;
 }

diff --git a/core/config/engine.h b/core/config/engine.h
@@ -49,6 +49,11 @@ class Engine {
 		Singleton(const StringName &p_name = StringName(), Object *p_ptr = nullptr, const StringName &p_class_name = StringName());
 	};
 
+	struct ExtensionClassDoc {
+		PackedByteArray compressed_data;
+		int uncompressed_size = 0;
+	};
+
 private:
 	friend class Main;
 
@@ -75,6 +80,8 @@ class Engine {
 	List<Singleton> singletons;
 	HashMap<StringName, Object *> singleton_ptrs;
 
+	Vector<ExtensionClassDoc> extensions_class_doc;
+
 	bool editor_hint = false;
 	bool project_manager_hint = false;
 
@@ -125,6 +132,9 @@ class Engine {
 	void remove_singleton(const StringName &p_name);
 	bool is_singleton_user_created(const StringName &p_name) const;
 
+	void add_extension_class_doc(PackedByteArray p_compressed_data, int p_uncompressed_size);
+	const Vector<ExtensionClassDoc> &get_extensions_class_doc() const;
+
 #ifdef TOOLS_ENABLED
 	_FORCE_INLINE_ void set_editor_hint(bool p_enabled) { editor_hint = p_enabled; }
 	_FORCE_INLINE_ bool is_editor_hint() const { return editor_hint; }

diff --git a/core/core_bind.cpp b/core/core_bind.cpp
@@ -1669,6 +1669,10 @@ ScriptLanguage *Engine::get_script_language(int p_index) const {
 	return ScriptServer::get_language(p_index);
 }
 
+void Engine::add_extension_class_doc(PackedByteArray p_compressed_data, int p_uncompressed_size) {
+	::Engine::get_singleton()->add_extension_class_doc(p_compressed_data, p_uncompressed_size);
+}
+
 void Engine::set_editor_hint(bool p_enabled) {
 	::Engine::get_singleton()->set_editor_hint(p_enabled);
 }
@@ -1728,6 +1732,8 @@ void Engine::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("unregister_singleton", "name"), &Engine::unregister_singleton);
 	ClassDB::bind_method(D_METHOD("get_singleton_list"), &Engine::get_singleton_list);
 
+	ClassDB::bind_method(D_METHOD("add_extension_class_doc", "compressed_data", "uncompressed_size"), &Engine::add_extension_class_doc);
+
 	ClassDB::bind_method(D_METHOD("register_script_language", "language"), &Engine::register_script_language);
 	ClassDB::bind_method(D_METHOD("unregister_script_language", "language"), &Engine::unregister_script_language);
 	ClassDB::bind_method(D_METHOD("get_script_language_count"), &Engine::get_script_language_count);

diff --git a/core/core_bind.h b/core/core_bind.h
@@ -513,6 +513,8 @@ class Engine : public Object {
 	int get_script_language_count();
 	ScriptLanguage *get_script_language(int p_index) const;
 
+	void add_extension_class_doc(PackedByteArray p_compressed_data, int p_uncompressed_size);
+
 	void set_editor_hint(bool p_enabled);
 	bool is_editor_hint() const;
 

diff --git a/doc/classes/Engine.xml b/doc/classes/Engine.xml
@@ -9,6 +9,15 @@
 	<tutorials>
 	</tutorials>
 	<methods>
+		<method name="add_extension_class_doc">
+			<return type="void" />
+			<param index="0" name="compressed_data" type="PackedByteArray" />
+			<param index="1" name="uncompressed_size" type="int" />
+			<description>
+				Registers additional class reference data for use in the editor help. The data should be UTF-8 encoded [url=$DOCS_URL/contributing/documentation/updating_the_class_reference.html]XML class reference[/url] compressed with zlib.
+				This method is meant for use in GDExtension plugins to add API documentation for the new classes exposed by the extension.
+			</description>
+		</method>
 		<method name="get_architecture_name" qualifiers="const">
 			<return type="String" />
 			<description>

diff --git a/editor/doc_tools.cpp b/editor/doc_tools.cpp
@@ -1619,12 +1619,15 @@ Error DocTools::save_classes(const String &p_default_path, const HashMap<String,
 	return OK;
 }
 
-Error DocTools::load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size) {
+Error DocTools::load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size, bool p_append) {
 	Vector<uint8_t> data;
 	data.resize(p_uncompressed_size);
 	int ret = Compression::decompress(data.ptrw(), p_uncompressed_size, p_data, p_compressed_size, Compression::MODE_DEFLATE);
 	ERR_FAIL_COND_V_MSG(ret == -1, ERR_FILE_CORRUPT, "Compressed file is corrupt.");
-	class_list.clear();
+
+	if (!p_append) {
+		class_list.clear();
+	}
 
 	Ref<XMLParser> parser = memnew(XMLParser);
 	Error err = parser->open_buffer(data);

diff --git a/editor/doc_tools.h b/editor/doc_tools.h
@@ -50,7 +50,7 @@ class DocTools {
 	Error save_classes(const String &p_default_path, const HashMap<String, String> &p_class_path, bool p_include_xml_schema = true);
 
 	Error _load(Ref<XMLParser> parser);
-	Error load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size);
+	Error load_compressed(const uint8_t *p_data, int p_compressed_size, int p_uncompressed_size, bool p_append = false);
 };
 
 #endif // DOC_TOOLS_H
diff --git a/editor/editor_help.cpp b/editor/editor_help.cpp
@@ -30,6 +30,7 @@
 
 #include "editor_help.h"
 
+#include "core/config/engine.h"
 #include "core/core_constants.h"
 #include "core/input/input.h"
 #include "core/object/script_language.h"
@@ -2289,7 +2290,13 @@ void EditorHelp::_load_doc_thread(void *p_udata) {
 
 void EditorHelp::_gen_doc_thread(void *p_udata) {
 	DocTools compdoc;
+	// Load core docs.
 	compdoc.load_compressed(_doc_data_compressed, _doc_data_compressed_size, _doc_data_uncompressed_size);
+	// Load user-registered extension docs.
+	const Vector<Engine::ExtensionClassDoc> &ext_doc = Engine::get_singleton()->get_extensions_class_doc();
+	for (int i = 0; i < ext_doc.size(); i++) {
+		compdoc.load_compressed(ext_doc[i].compressed_data.ptr(), ext_doc[i].compressed_data.size(), ext_doc[i].uncompressed_size, true);
+	}
 	doc->merge_from(compdoc); // Ensure all is up to date.
 
 	Ref<DocCache> cache_res;