Cleanup + adding docblocks

app/Dom/Node.php

@@ -14,7 +14,7 @@ class Node implements \ArrayAccess, \Iterator
 	/** @var int */
 	private $_idx;
 
-	/** @var string */
+	/** @var ?string */
 	protected $name;
 
 	/** @var Node */
@@ -23,6 +23,12 @@ class Node implements \ArrayAccess, \Iterator
 	/** @var Node[] */
 	protected $children;
 
+	/**
+	 * Create a new DOM node.
+	 *
+	 * @param Node    $parent the parent this node is nested under
+	 * @param ?string $name   the name of the node, if one exists
+	 */
 	public function __construct(Node $parent, ?string $name)
 	{
 		$this->parent = $parent;
@@ -30,37 +36,74 @@ class Node implements \ArrayAccess, \Iterator
 		$this->name = $name;
 	}
 
-	public function setName(string $name)
+	/**
+	 * Set the node's name.
+	 *
+	 * @param  string $name
+	 * @return void
+	 */
+	public function setName(string $name): void
 	{
 		$this->name = $name;
 	}
 
+	/**
+	 * Get the node's name.
+	 *
+	 * @return string
+	 */
 	public function getName(): string
 	{
 		return $this->name;
 	}
 
+	/**
+	 * Check whether the node has a name set.
+	 *
+	 * @return bool
+	 */
 	public function hasName(): bool
 	{
 		return isset($this->name);
 	}
 
+	/**
+	 * Get this node's parent node.
+	 *
+	 * @return Node
+	 */
 	public function getParent(): Node
 	{
 		return $this->parent;
 	}
 
+	/**
+	 * Check whether this node has any child nodes.
+	 *
+	 * @return bool
+	 */
 	public function hasChildren(): bool
 	{
 		return sizeof($this->children) > 0;
 	}
 
+	/**
+	 * Fetch this node's children.
+	 *
+	 * @return Node[]
+	 */
 	public function getChildren(): array
 	{
 		return $this->children;
 	}
 
-	public function addChild(Node $child)
+	/**
+	 * Add a node to this node's children.
+	 *
+	 * @param  Node $child
+	 * @return void
+	 */
+	public function addChild(Node $child): void
 	{
 		$this->children[] = $child;
 	}

app/Dom/NodeFunctionValue.php

@@ -11,20 +11,38 @@ namespace App\Dom;
  */
 class NodeFunctionValue extends NodeFunction
 {
-	/** @var mixed */
+	/** @var scalar */
 	protected $value;
 
+	/**
+	 * Create a new function node which directly contains a value.
+	 *
+	 * @param Node    $parent
+	 * @param ?string $name
+	 * @param scalar  $value
+	 */
 	public function __construct(Node $parent, ?string $name, $value)
 	{
 		parent::__construct($parent, $name);
 		$this->value = $value;
 	}
 
-	public function setValue($value)
+	/**
+	 * Set the value of this node.
+	 *
+	 * @param  scalar $value
+	 * @return void
+	 */
+	public function setValue($value): void
 	{
 		$this->value = $value;
 	}
 
+	/**
+	 * Get the value of this node.
+	 *
+	 * @return scalar
+	 */
 	public function getValue()
 	{
 		return $this->value;

app/Dom/NodeValue.php

@@ -11,20 +11,38 @@ namespace App\Dom;
  */
 class NodeValue extends Node
 {
-	/** @var mixed */
+	/** @var scalar */
 	protected $value;
 
+	/**
+	 * Create a new node containing a scalar value.
+	 *
+	 * @param Node    $parent
+	 * @param ?string $name
+	 * @param scalar  $value
+	 */
 	public function __construct(Node $parent, ?string $name, $value)
 	{
 		parent::__construct($parent, $name);
 		$this->value = $value;
 	}
 
-	public function setValue($value)
+	/**
+	 * Set the value of this node.
+	 *
+	 * @param  scalar $value
+	 * @return void
+	 */
+	public function setValue($value): void
 	{
 		$this->value = $value;
 	}
 
+	/**
+	 * Get the value of this node.
+	 *
+	 * @return scalar
+	 */
 	public function getValue()
 	{
 		return $this->value;

app/Engine/Engine.php

@@ -38,15 +38,15 @@ class Engine
 		return $this;
 	}
 
-	public function compile(string $document_string): string
+	public function compile(string $document_string, IOptions $options): string
 	{
 		$document = $this->unserialize->unserialize($document_string);
-		$document = $this->compile->compile($document);
+		$document = $this->compile->compile($document, $options);
 		return $this->serialize->serialize($document);
 	}
 
-	public function compileDocument(\App\Dom\Document $document): \App\Dom\Document
+	public function compileDocument(\App\Dom\Document $document, IOptions $options): \App\Dom\Document
 	{
-		return $this->compile->compile($document);
+		return $this->compile->compile($document, $options);
 	}
 }

app/Engine/ICompile.php

@@ -11,5 +11,12 @@ namespace App\Engine;
  */
 interface ICompile
 {
-	public function compile(\App\Dom\Document $document, IOptions $options);
+	/**
+	 * Perform compilation/transform process on a document.
+	 *
+	 * @param  \App\Dom\Document $document document to compile
+	 * @param  IOptions          $options  options to control compilation process
+	 * @return \App\Dom\Document the compiled document
+	 */
+	public function compile(\App\Dom\Document $document, IOptions $options): \App\Dom\Document;
 }

app/Serialize/Yaml.php

@@ -14,6 +14,12 @@ use App\Dom\NodeFunctionValue;
 
 class Yaml implements ISerialize, IUnserialize
 {
+	/**
+	 * Convert a YAML string into a Dom\Document.
+	 *
+	 * @param  string   $document
+	 * @return Document
+	 */
 	public function unserialize(string $document): Document
 	{
 		$data = SymfonyYaml::parse($document, SymfonyYaml::PARSE_CUSTOM_TAGS);
@@ -22,6 +28,12 @@ class Yaml implements ISerialize, IUnserialize
 		return $document;
 	}
 
+	/**
+	 * Convert a Dom\Document into a YAML string.
+	 *
+	 * @param  Document $document
+	 * @return string
+	 */
 	public function serialize(Document $document): string
 	{
 		$data = $this->domToArray($document);
@@ -58,6 +70,12 @@ class Yaml implements ISerialize, IUnserialize
 		return $result;
 	}
 
+	/**
+	 * Serialize a single node, only meant to be used as part of/by domToArray.
+	 *
+	 * @param  Node  $node
+	 * @return mixed
+	 */
 	private function serializeNode(Node $node)
 	{
 		switch (true)
@@ -71,9 +89,18 @@ class Yaml implements ISerialize, IUnserialize
 			default:
 				return $node->hasName() ? [$node->getName() => $this->domToArray($node)] : [$this->domToArray($node)];
 		}
-		throw new \Exception('Unrecognized node type: '.get_class($node));
 	}
 
+	/**
+	 * Convert an array returned from Symfony's Yaml component when parsing a
+	 * yaml document and convert it into a Dom\Document.
+	 *
+	 * Children are pushed directly onto the passed $parent node
+	 *
+	 * @param  Node               $parent node that the data is to be unserialized under
+	 * @param  array<mixed,mixed> $data   the data to unserialize
+	 * @return void
+	 */
 	protected function arrayToDom(Node $parent, array $data)
 	{
 		foreach ($data as $k => $v)
@@ -93,6 +120,10 @@ class Yaml implements ISerialize, IUnserialize
 				{
 					$fun_node = new NodeFunctionValue($node, $fun_name, $fun_value);
 				}
+				else
+				{
+					throw new \Exception('Cannot unserialize value from function node--is not array or scalar');
+				}
 				$node->addChild($fun_node);
 			}
 			else
@@ -106,6 +137,10 @@ class Yaml implements ISerialize, IUnserialize
 				{
 					$node = new NodeValue($parent, is_string($k) ? $k : null, $v);
 				}
+				else
+				{
+					throw new \Exception('Cannot unserialize value from YAML--value is not TaggedValue, array or scalar');
+				}
 			}
 			$parent->addChild($node);
 		}