From 9064a7993104ba9d3535cfe32bfbc59a928511f6 Mon Sep 17 00:00:00 2001
From: pew <pewtheworstdeveever@protonmail.com>
Date: Sat, 25 Feb 2023 18:13:20 +0300
Subject: [PATCH] Preparations for publishing on the Asset Library

---
 README.md                        | 13 +++++++++++++
 addons/godot_xml/xml.gd          | 19 ++++++++++++++-----
 addons/godot_xml/xml_document.gd |  9 +++++++--
 3 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 5b42ad4..9d50608 100644
--- a/README.md
+++ b/README.md
@@ -2,3 +2,16 @@
 
 This addon adds support for manipulating XML data in Godot 4 with ease.
 
+## Features
+
+- Loading and dumping XML data into/from a convenient class-based format;
+- Beautifying XML;
+- Converting XML into dictionaries.
+
+## API
+
+All functions and attributes that are meant for use by you do not have `_` before their name
+and are also listed before any internal function.
+
+All other functions and attributes are **not meant** to be used by you, though you
+can edit them as you like thanks to the license.
diff --git a/addons/godot_xml/xml.gd b/addons/godot_xml/xml.gd
index 6910207..7fc746e 100644
--- a/addons/godot_xml/xml.gd
+++ b/addons/godot_xml/xml.gd
@@ -15,7 +15,6 @@ enum XMLNodeType {
 ## Parses file content as XML into [XMLDocument].
 ## The file at a specified [code]path[/code] [b]must[/b] be readable.
 ## File content [b]must[/b] be a valid XML document.
-## Returns the parsed document.
 static func parse_file(path: String) -> XMLDocument:
 	var file = FileAccess.open(path, FileAccess.READ)
 	var xml: PackedByteArray = file.get_as_text().to_utf8_buffer()
@@ -26,18 +25,19 @@ static func parse_file(path: String) -> XMLDocument:
 
 ## Parses string as XML into [XMLDocument].
 ## String content [b]must[/b] be a valid XML document.
-## Returns the parsed document.
 static func parse_str(xml: String) -> XMLDocument:
 	return _parse(xml.to_utf8_buffer())
 
 
 ## Parses byte buffer as XML into [XMLDocument].
 ## Buffer content [b]must[/b] be a valid XML document.
-## Returns the parsed document.
 static func parse_buffer(xml: PackedByteArray) -> XMLDocument:
 	return _parse(xml)
 
 
+## Dumps [param document] to the specified file.
+## The file at a specified [code]path[/code] [b]must[/b] be writeable.
+## Set [param beautify] to [code]true[/code] if you want indented output.
 static func dump_file(path: String, document: XMLDocument, beautify: bool = false):
 	var file = FileAccess.open(path, FileAccess.WRITE)
 	var xml: String = dump_str(document, beautify)
@@ -45,11 +45,15 @@ static func dump_file(path: String, document: XMLDocument, beautify: bool = fals
 	file = null
 
 
-static func dump_buffer(document: XMLDocument, beautify: bool = false):
+## Dumps [param document] to a [PackedByteArray].
+## Set [param beautify] to [code]true[/code] if you want indented output.
+static func dump_buffer(document: XMLDocument, beautify: bool = false) -> PackedByteArray:
 	return dump_str(document, beautify).to_utf8_buffer()
 
 
-static func dump_str(document: XMLDocument, beautify: bool = false):
+## Dumps [param document] to [String].
+## Set [param beautify] to [code]true[/code] if you want indented output.
+static func dump_str(document: XMLDocument, beautify: bool = false) -> String:
 	return _dump(document, beautify)
 
 
@@ -143,6 +147,7 @@ static func _parse(xml: PackedByteArray) -> XMLDocument:
 	
 	return doc
 
+
 static func _make_node(queue: Array, parser: XMLParser):
 	var node_type = parser.get_node_type()
 
@@ -159,6 +164,7 @@ static func _make_node(queue: Array, parser: XMLParser):
 	#print(parser.get_node_data())
 	#print(parser.get_node_name())
 
+
 static func _make_node_element(parser: XMLParser):
 	var node: XMLNode = XMLNode.new()
 
@@ -170,6 +176,7 @@ static func _make_node_element(parser: XMLParser):
 
 	return node
 
+
 static func _make_node_element_end(parser: XMLParser) -> XMLNode:
 	var node: XMLNode = XMLNode.new()
 
@@ -181,10 +188,12 @@ static func _make_node_element_end(parser: XMLParser) -> XMLNode:
 
 	return node
 
+
 static func _attach_node_data(node: XMLNode, parser: XMLParser) -> void:
 	if node.content.is_empty():
 		node.content = parser.get_node_data().strip_edges().lstrip(" ").rstrip(" ")
 
+
 static func _get_attributes(parser: XMLParser) -> Dictionary:
 	var attrs: Dictionary = {}
 	var attr_count: int = parser.get_attribute_count()
diff --git a/addons/godot_xml/xml_document.gd b/addons/godot_xml/xml_document.gd
index 3cc6079..5c04ce5 100644
--- a/addons/godot_xml/xml_document.gd
+++ b/addons/godot_xml/xml_document.gd
@@ -4,10 +4,15 @@ class_name XMLDocument extends RefCounted
 ## The XML root node.
 var root: XMLNode
 
+## Converts this tree into a [Dictionary].
+## Set [param include_empty_fields] to [code]true[/code] if you want
+## to include fields that do not have any content (e.g., a node without
+## a single attribute or without content).
+## [param node_content_field_name] controls which field node's content is assigned to.
 func to_dict(
 	include_empty_fields: bool = false,
 	node_content_field_name: String = "__content__",
-):
+) -> Dictionary:
 	return _to_dict(root, include_empty_fields, node_content_field_name)
 
 
@@ -15,7 +20,7 @@ static func _to_dict(
 	node: XMLNode,
 	include_empty_fields: bool = false,
 	node_content_field_name: String = "__content__",
-):
+) -> Dictionary:
 	var data: Dictionary = {}
 
 	if include_empty_fields: