Updated doc blocks

Author: paquettg

CHANGELOG.md

@@ -22,3 +22,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Moved the Mock object to the tests directory, where it belongs.
 - Changes from `PSR-0` to `PSR-4` autoloading.
 - Updated `CONTRIBUTING.md` contents.
+- Updated docblocks.

src/PHPHtmlParser/Dom.php

@@ -2,10 +2,16 @@
 namespace PHPHtmlParser;
 
 use PHPHtmlParser\Dom\AbstractNode;
+use PHPHtmlParser\Dom\Collection;
 use PHPHtmlParser\Dom\HtmlNode;
 use PHPHtmlParser\Dom\TextNode;
+use PHPHtmlParser\Exceptions\ChildNotFoundException;
+use PHPHtmlParser\Exceptions\CircularException;
+use PHPHtmlParser\Exceptions\CurlException;
 use PHPHtmlParser\Exceptions\NotLoadedException;
+use PHPHtmlParser\Exceptions\ParentNotFoundException;
 use PHPHtmlParser\Exceptions\StrictException;
+use PHPHtmlParser\Exceptions\UnknownChildTypeException;
 use stringEncode\Encode;
 
 /**
@@ -109,6 +115,8 @@ class Dom
      * Returns the inner html of the root node.
      *
      * @return string
+     * @throws ChildNotFoundException
+     * @throws UnknownChildTypeException
      */
     public function __toString(): string
     {
@@ -128,11 +136,13 @@ public function __get($name)
 
     /**
      * Attempts to load the dom from any resource, string, file, or URL.
-     *
      * @param string $str
-     * @param array $options
+     * @param array  $options
      * @return Dom
-     * @chainable
+     * @throws ChildNotFoundException
+     * @throws CircularException
+     * @throws CurlException
+     * @throws StrictException
      */
     public function load(string $str, array $options = []): Dom
     {
@@ -151,11 +161,12 @@ public function load(string $str, array $options = []): Dom
 
     /**
      * Loads the dom from a document file/url
-     *
      * @param string $file
-     * @param array $options
+     * @param array  $options
      * @return Dom
-     * @chainable
+     * @throws ChildNotFoundException
+     * @throws CircularException
+     * @throws StrictException
      */
     public function loadFromFile(string $file, array $options = []): Dom
     {
@@ -165,12 +176,14 @@ public function loadFromFile(string $file, array $options = []): Dom
     /**
      * Use a curl interface implementation to attempt to load
      * the content from a url.
-     *
-     * @param string $url
-     * @param array $options
-     * @param CurlInterface $curl
+     * @param string                            $url
+     * @param array                             $options
+     * @param CurlInterface|null $curl
      * @return Dom
-     * @chainable
+     * @throws ChildNotFoundException
+     * @throws CircularException
+     * @throws CurlException
+     * @throws StrictException
      */
     public function loadFromUrl(string $url, array $options = [], CurlInterface $curl = null): Dom
     {
@@ -186,11 +199,12 @@ public function loadFromUrl(string $url, array $options = [], CurlInterface $cur
     /**
      * Parsers the html of the given string. Used for load(), loadFromFile(),
      * and loadFromUrl().
-     *
      * @param string $str
-     * @param array $option
+     * @param array  $option
      * @return Dom
-     * @chainable
+     * @throws ChildNotFoundException
+     * @throws CircularException
+     * @throws StrictException
      */
     public function loadStr(string $str, array $option = []): Dom
     {
@@ -228,10 +242,11 @@ public function setOptions(array $options): Dom
 
     /**
      * Find elements by css selector on the root node.
-     *
-     * @param string $selector
-     * @param int $nth
-     * @return mixed
+     * @param string   $selector
+     * @param int|null $nth
+     * @return mixed|Collection|null
+     * @throws ChildNotFoundException
+     * @throws NotLoadedException
      */
     public function find(string $selector, int $nth = null)
     {
@@ -242,9 +257,11 @@ public function find(string $selector, int $nth = null)
 
     /**
      * Find element by Id on the root node
-     *
      * @param int $id
-     * @return mixed
+     * @return bool|AbstractNode
+     * @throws ChildNotFoundException
+     * @throws NotLoadedException
+     * @throws ParentNotFoundException
      */
     public function findById(int $id)
     {
@@ -356,10 +373,11 @@ public function clearNoSlashTags(): Dom
 
     /**
      * Simple wrapper function that returns the first child.
-     *
-     * @return \PHPHtmlParser\Dom\AbstractNode
+     * @return AbstractNode
+     * @throws ChildNotFoundException
+     * @throws NotLoadedException
      */
-    public function firstChild(): \PHPHtmlParser\Dom\AbstractNode
+    public function firstChild(): AbstractNode
     {
         $this->isLoaded();
 
@@ -368,10 +386,11 @@ public function firstChild(): \PHPHtmlParser\Dom\AbstractNode
 
     /**
      * Simple wrapper function that returns the last child.
-     *
-     * @return \PHPHtmlParser\Dom\AbstractNode
+     * @return AbstractNode
+     * @throws ChildNotFoundException
+     * @throws NotLoadedException
      */
-    public function lastChild(): \PHPHtmlParser\Dom\AbstractNode
+    public function lastChild(): AbstractNode
     {
         $this->isLoaded();
 
@@ -382,6 +401,7 @@ public function lastChild(): \PHPHtmlParser\Dom\AbstractNode
      * Simple wrapper function that returns count of child elements
      *
      * @return int
+     * @throws NotLoadedException
      */
     public function countChildren(): int
     {
@@ -394,6 +414,7 @@ public function countChildren(): int
      * Get array of children
      *
      * @return array
+     * @throws NotLoadedException
      */
     public function getChildren(): array
     {
@@ -406,6 +427,7 @@ public function getChildren(): array
      * Check if node have children nodes
      *
      * @return bool
+     * @throws NotLoadedException
      */
     public function hasChildren(): bool
     {
@@ -417,9 +439,10 @@ public function hasChildren(): bool
     /**
      * Simple wrapper function that returns an element by the
      * id.
-     *
-     * @param string $id
-     * @return \PHPHtmlParser\Dom\AbstractNode|null
+     * @param $id
+     * @return mixed|Collection|null
+     * @throws ChildNotFoundException
+     * @throws NotLoadedException
      */
     public function getElementById($id)
     {
@@ -431,9 +454,10 @@ public function getElementById($id)
     /**
      * Simple wrapper function that returns all elements by
      * tag name.
-     *
      * @param string $name
-     * @return mixed
+     * @return mixed|Collection|null
+     * @throws ChildNotFoundException
+     * @throws NotLoadedException
      */
     public function getElementsByTag(string $name)
     {
@@ -445,9 +469,10 @@ public function getElementsByTag(string $name)
     /**
      * Simple wrapper function that returns all elements by
      * class name.
-     *
      * @param string $class
-     * @return mixed
+     * @return mixed|Collection|null
+     * @throws ChildNotFoundException
+     * @throws NotLoadedException
      */
     public function getElementsByClass(string $class)
     {
@@ -528,6 +553,11 @@ protected function clean(string $str): string
 
     /**
      * Attempts to parse the html in content.
+     *
+     * @return void
+     * @throws ChildNotFoundException
+     * @throws CircularException
+     * @throws StrictException
      */
     protected function parse(): void
     {
@@ -632,7 +662,7 @@ protected function parseTag(): array
         $tag  = strtolower($this->content->copyByToken('slash', true));
         if (trim($tag) == '')
         {
-            // no tag found, invalide < found
+            // no tag found, invalid < found
             return $return;
         }
         $node = new HtmlNode($tag);
@@ -746,6 +776,7 @@ protected function parseTag(): array
      * Attempts to detect the charset that the html was sent in.
      *
      * @return bool
+     * @throws ChildNotFoundException
      */
     protected function detectCharset(): bool
     {

src/PHPHtmlParser/Dom/AbstractNode.php

@@ -11,22 +11,20 @@
 
 /**
  * Dom node object.
- *
- * @property string outerhtml
- * @property string innerhtml
- * @property string text
- * @property int prev
- * @property int next
- * @property \PHPHtmlParser\Dom\Tag tag
+ * @property string    outerhtml
+ * @property string    innerhtml
+ * @property string    text
+ * @property int       prev
+ * @property int       next
+ * @property Tag       tag
  * @property InnerNode parent
  */
 abstract class AbstractNode
 {
     private static $count = 0;
     /**
      * Contains the tag name/type
-     *
-     * @var \PHPHtmlParser\Dom\Tag
+     * @var Tag
      */
     protected $tag;
 
@@ -170,11 +168,10 @@ public function getParent()
 
     /**
      * Sets the parent node.
-     *
      * @param InnerNode $parent
      * @return AbstractNode
+     * @throws ChildNotFoundException
      * @throws CircularException
-     * @chainable
      */
     public function setParent(InnerNode $parent): AbstractNode
     {
@@ -286,8 +283,8 @@ public function hasNextSibling(): bool
 
     /**
      * Attempts to get the next sibling.
-     *
      * @return AbstractNode
+     * @throws ChildNotFoundException
      * @throws ParentNotFoundException
      */
     public function nextSibling(): AbstractNode
@@ -300,9 +297,9 @@ public function nextSibling(): AbstractNode
     }
 
     /**
-     * Attempts to get the previous sibling
-     *
+     * Attempts to get the previous sibling.
      * @return AbstractNode
+     * @throws ChildNotFoundException
      * @throws ParentNotFoundException
      */
     public function previousSibling(): AbstractNode
@@ -441,11 +438,11 @@ public function ancestorByTag(string $tag): AbstractNode
 
     /**
      * Find elements by css selector
-     *
-     * @param string $selector
-     * @param int $nth
-     * @param bool $depthFirst
-     * @return mixed
+     * @param string   $selector
+     * @param int|null $nth
+     * @param bool     $depthFirst
+     * @return mixed|Collection|null
+     * @throws ChildNotFoundException
      */
     public function find(string $selector, int $nth = null, bool $depthFirst = false)
     {
@@ -467,9 +464,10 @@ public function find(string $selector, int $nth = null, bool $depthFirst = false
 
     /**
      * Find node by id
-     *
      * @param int $id
      * @return bool|AbstractNode
+     * @throws ChildNotFoundException
+     * @throws ParentNotFoundException
      */
     public function findById(int $id)
     {

src/PHPHtmlParser/Dom/Collection.php

@@ -64,7 +64,6 @@ public function __get($key)
      * the collection.
      *
      * @return string
-     * @throws EmptyCollectionException
      */
     public function __toString(): string
     {

src/PHPHtmlParser/Dom/HtmlNode.php

@@ -67,8 +67,8 @@ public function setHtmlSpecialCharsDecode($htmlSpecialCharsDecode = false): void
 
     /**
      * Gets the inner html of this node.
-     *
      * @return string
+     * @throws ChildNotFoundException
      * @throws UnknownChildTypeException
      */
     public function innerHtml(): string
@@ -113,8 +113,9 @@ public function innerHtml(): string
     /**
      * Gets the html of this node, including it's own
      * tag.
-     *
      * @return string
+     * @throws ChildNotFoundException
+     * @throws UnknownChildTypeException
      */
     public function outerHtml(): string
     {