Cleaned up the comments and php docs

Author: paquettg

src/PHPHtmlParser/Content.php

@@ -34,13 +34,23 @@ class Content {
 	protected $slash = " />\r\n\t";
 	protected $attr  = ' >';
 
+	/**
+	 * Sets up the content block with its content.
+	 *
+	 * @param $content
+	 */
 	public function __construct($content)
 	{
 		$this->content = $content;
 		$this->size    = strlen($content);
 		$this->pos     = 0;
 	}
 
+	/**
+	 * Returns the current position of the parser.
+	 *
+	 * @return int
+	 */
 	public function getPosition()
 	{
 		return $this->pos;
@@ -192,7 +202,7 @@ public function skip($string, $copy = false)
 	{
 		$len = strspn($this->content, $string, $this->pos);
 
-		// make it chainable if they don't want a copy
+		// make it chain-able if they don't want a copy
 		$return = $this;
 		if ($copy)
 		{

src/PHPHtmlParser/Dom.php

@@ -1,6 +1,7 @@
 <?php
 namespace PHPHtmlParser;
 
+use PHPHtmlPArser\Dom\AbstractNode;
 use PHPHtmlParser\Dom\HtmlNode;
 use PHPHtmlParser\Dom\TextNode;
 use PHPHtmlParser\Exceptions\NotLoadedException;
@@ -363,7 +364,7 @@ protected function clean($str)
 		$str = mb_eregi_replace("<\s*style[^>]*[^/]>(.*?)<\s*/\s*style\s*>", '', $str);
 		$str = mb_eregi_replace("<\s*style\s*>(.*?)<\s*/\s*style\s*>", '', $str);
 
-		// strip out preformatted tags
+		// strip out pre-formatted tags
 		$str = mb_eregi_replace("<\s*(?:code)[^>]*>(.*?)<\s*/\s*(?:code)\s*>", '', $str);
 
 		// strip out server side scripts
@@ -422,6 +423,7 @@ protected function parse()
 					continue;
 				}
 
+				/** @var AbstractNode $node */
 				$node = $info['node'];
 				$activeNode->addChild($node);
 
@@ -575,7 +577,7 @@ protected function parseTag()
 			if ( $this->options->strict)
 			{
 				$character = $this->content->getPosition();
-				throw new StrictException("Tag '$tag' is not self clossing! (character #$character)");
+				throw new StrictException("Tag '$tag' is not self closing! (character #$character)");
 			}
 
 			// We force self closing on this tag.

src/PHPHtmlParser/Dom/AbstractNode.php

@@ -58,6 +58,9 @@ abstract class AbstractNode {
 	 */
 	protected $encode;
 
+	/**
+	 * Creates a unique spl hash for this node.
+	 */
 	public function __construct()
 	{
 		$this->id = spl_object_hash($this);
@@ -179,7 +182,9 @@ public function propagateEncoding(Encode $encode)
 		// check children
 		foreach ($this->children as $id => $child)
 		{
-			$child['node']->propagateEncoding($encode);
+			/** @var AbstractNode $node */
+			$node = $child['node'];
+			$node->propagateEncoding($encode);
 		}
 	}
 
@@ -378,7 +383,7 @@ public function isChild ($id)
 	}
 
 	/**
-	 * Checks if the given node id is a decendant of the 
+	 * Checks if the given node id is a descendant of the
 	 * current node.
 	 *
 	 * @param int $id
@@ -393,12 +398,12 @@ public function isDescendant($id)
 
 		foreach ($this->children as $childId => $child)
 		{
-			if ($child['node']->hasChildren())
+			/** @var AbstractNode $node */
+			$node = $child['node'];
+			if ($node->hasChildren() &&
+				$node->isDescendant($id))
 			{
-				if ($child['node']->isDescendant($id))
-				{
-					return true;
-				}
+				return true;
 			}
 		}
 
@@ -591,7 +596,7 @@ public function ancestorByTag($tag)
 	 *
 	 * @param string $selector
 	 * @param int	 $nth
-	 * @return array
+	 * @return array|AbstractNode
 	 */
 	public function find($selector, $nth = null)
 	{
@@ -619,10 +624,10 @@ public function find($selector, $nth = null)
 	 *
 	 * Far future enhancement
 	 * Look at all the parent tags of this image to see if they specify a class or id that has an img selector that specifies a height or width
-	 * Note that in this case, the class or id will have the img subselector for it to apply to the image.
+	 * Note that in this case, the class or id will have the img sub-selector for it to apply to the image.
 	 *
 	 * ridiculously far future development
-	 * If the class or id is specified in a SEPARATE css file thats not on the page, go get it and do what we were just doing for the ones on the page.
+	 * If the class or id is specified in a SEPARATE css file that's not on the page, go get it and do what we were just doing for the ones on the page.
 	 *
 	 * @author John Schlick
 	 * @return array an array containing the 'height' and 'width' of the image on the page or -1 if we can't figure it out.
@@ -651,9 +656,9 @@ public function get_display_size()
 		// Now look for an inline style.
 		if ( ! is_null($this->tag->getAttribute('style')))
 		{
-			// Thanks to user gnarf from stackoverflow for this regular expression.
+			// Thanks to user 'gnarf' from stackoverflow for this regular expression.
 			$attributes = [];
-			preg_match_all("/([\w-]+)\s*:\s*([^;]+)\s*;?/", $this->tag->getAttribute['style'], $matches, PREG_SET_ORDER);
+			preg_match_all("/([\w-]+)\s*:\s*([^;]+)\s*;?/", $this->tag->getAttribute('style'), $matches, PREG_SET_ORDER);
 			foreach ($matches as $match) 
 			{
 				$attributes[$match[1]] = $match[2];

src/PHPHtmlParser/Dom/HtmlNode.php

@@ -170,14 +170,16 @@ public function text($lookInChildren = false)
 		$text = '';
 		foreach ($this->children as $child)
 		{
-			if ($child['node'] instanceof TextNode)
+			/** @var AbstractNode $node */
+			$node = $child['node'];
+			if ($node instanceof TextNode)
 			{
 				$text .= $child['node']->text;
 			}
 			elseif($lookInChildren and
-			       $child['node'] instanceof HtmlNode)
+			       $node instanceof HtmlNode)
 			{
-				$text .= $child['node']->text($lookInChildren);
+				$text .= $node->text($lookInChildren);
 			}
 		}
 

src/PHPHtmlParser/Dom/Tag.php

@@ -25,7 +25,7 @@ class Tag {
 	 *
 	 * @var bool
 	 */
-	protected $selfclosing = false;
+	protected $selfClosing = false;
 
 	/**
 	 * Tag noise
@@ -39,16 +39,33 @@ class Tag {
 	 */
 	protected $encode = null;
 
+	/**
+	 * Sets up the tag with a name.
+	 *
+	 * @param $name
+	 */
 	public function __construct($name)
 	{
 		$this->name = $name;
 	}
 
+	/**
+	 * Magic method to get any of the attributes.
+	 *
+	 * @param string $key
+	 * @return mixed
+	 */
 	public function __get($key)
 	{
 		return$this->getAttribute($key);
 	}
 
+	/**
+	 * Magic method to set any attribute.
+	 *
+	 * @param string $key
+	 * @param mixed $value
+	 */
 	public function __set($key, $value)
 	{
 		$this->setAttribute($key, $value);
@@ -71,7 +88,7 @@ public function name()
 	 */
 	public function selfClosing()
 	{
-		$this->selfclosing = true;
+		$this->selfClosing = true;
 		return $this;
 	}
 
@@ -82,9 +99,14 @@ public function selfClosing()
 	 */
 	public function isSelfClosing()
 	{
-		return $this->selfclosing;
+		return $this->selfClosing;
 	}
 
+	/**
+	 * Sets the encoding type to be used.
+	 *
+	 * @param Encode $encode
+	 */
 	public function setEncoding(Encode $encode)
 	{
 		$this->encode = $encode;
@@ -205,7 +227,7 @@ public function makeOpeningTag()
 			}
 		}
 
-		if ($this->selfclosing)
+		if ($this->selfClosing)
 		{
 			return $return.' />';
 		}
@@ -222,7 +244,7 @@ public function makeOpeningTag()
 	 */
 	public function makeClosingTag()
 	{
-		if ($this->selfclosing)
+		if ($this->selfClosing)
 		{
 			return '';
 		}

src/PHPHtmlParser/Selector.php

@@ -8,7 +8,7 @@
 class Selector {
 
 	/** 
-	 * Pattern of CSS selectors, modified from mootools
+	 * Pattern of CSS selectors, modified from 'mootools'
 	 *
 	 * @var string
 	 */
@@ -117,7 +117,7 @@ protected function parseSelectorString($selector)
 				$value = $match[3];
 			}
 
-			// and final attribute selecter
+			// and final attribute selector
 			if ( ! empty($match[4]))
 			{
 				$key = strtolower($match[4]);
@@ -177,6 +177,7 @@ protected function seek(array $nodes, array $rule, array $options)
 			is_numeric($rule['key']))
 		{
 			$count = 0;
+			/** @var AbstractNode $node */
 			foreach ($nodes as $node)
 			{
 				if ($rule['tag'] == '*' OR $rule['tag'] == $node->getTag()->name())
@@ -195,6 +196,7 @@ protected function seek(array $nodes, array $rule, array $options)
 		$options = $this->flattenOptions($options);
 
 		$return = [];
+		/** @var AbstractNode $node */
 		foreach ($nodes as $node)
 		{
 			// check if we are a leaf
@@ -226,7 +228,7 @@ protected function seek(array $nodes, array $rule, array $options)
 				if ( ! empty($rule['tag']) AND $rule['tag'] != $child->getTag()->name() AND
 					$rule['tag'] != '*')
 				{
-					// child faild tag check
+					// child failed tag check
 					$pass = false;
 				}
 

tests/Options/StrictTest.php

@@ -30,7 +30,7 @@ public function testConfigStrictMissingSelfClosing()
 		}
 		catch (StrictException $e)
 		{
-			$this->assertEquals("Tag 'br' is not self clossing! (character #31)", $e->getMessage());
+			$this->assertEquals("Tag 'br' is not self closing! (character #31)", $e->getMessage());
 		}
 	}