Preparations for publishing on the Asset Library

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.

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,30 +25,35 @@ 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)
 	file.store_string(xml)
 	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()

addons/godot_xml/xml_document.gd

@@ -4,18 +4,23 @@ 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)
 
 
 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: