Skip to content

Commit

Permalink
Comments update.
Browse files Browse the repository at this point in the history
  • Loading branch information
@ivopetkov
ivopetkov committed Aug 24, 2018
1 parent da1a8e1 commit 5ff1c48
Show file tree
Hide file tree
Showing 5 changed files with 85 additions and 65 deletions.
63 changes: 33 additions & 30 deletions src/HTML5DOMDocument.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
namespace IvoPetkov;

/**
*
* Represents a live (can be manipulated) representation of a HTML5 document.
*/
class HTML5DOMDocument extends \DOMDocument
{
Expand All @@ -31,14 +31,14 @@ class HTML5DOMDocument extends \DOMDocument
static private $newObjectsCache = [];

/**
* Indicates whether an HTML code is loaded
* Indicates whether an HTML code is loaded.
*
* @var boolean
*/
private $loaded = false;

/**
* Creates a new \IvoPetkov\HTML5DOMDocument object
* Creates a new HTML5DOMDocument object.
*
* @param string $version The version number of the document as part of the XML declaration.
* @param string $encoding The encoding of the document as part of the XML declaration.
Expand All @@ -50,11 +50,11 @@ public function __construct(string $version = null, string $encoding = null)
}

/**
* Load HTML from a string
* Load HTML from a string.
*
* @param string $source The HTML code
* @param int $options Additional Libxml parameters
* @return boolean TRUE on success or FALSE on failure
* @param string $source The HTML code.
* @param int $options Additional Libxml parameters.
* @return boolean TRUE on success or FALSE on failure.
*/
public function loadHTML($source, $options = 0)
{
Expand Down Expand Up @@ -212,20 +212,20 @@ public function loadHTML($source, $options = 0)
}

/**
* Load HTML from a file
* Load HTML from a file.
*
* @param string $filename The path to the HTML file
* @param int $options Additional Libxml parameters
* @param string $filename The path to the HTML file.
* @param int $options Additional Libxml parameters.
*/
public function loadHTMLFile($filename, $options = 0)
{
return $this->loadHTML(file_get_contents($filename), $options);
}

/**
* Adds the HTML tag to the document if missing
* Adds the HTML tag to the document if missing.
*
* @return boolean TRUE on success, FALSE otherwise
* @return boolean TRUE on success, FALSE otherwise.
*/
private function addHtmlElementIfMissing(): bool
{
Expand All @@ -240,9 +240,9 @@ private function addHtmlElementIfMissing(): bool
}

/**
* Adds the HEAD tag to the document if missing
* Adds the HEAD tag to the document if missing.
*
* @return boolean TRUE on success, FALSE otherwise
* @return boolean TRUE on success, FALSE otherwise.
*/
private function addHeadElementIfMissing(): bool
{
Expand All @@ -263,9 +263,9 @@ private function addHeadElementIfMissing(): bool
}

/**
* Adds the BODY tag to the document if missing
* Adds the BODY tag to the document if missing.
*
* @return boolean TRUE on success, FALSE otherwise
* @return boolean TRUE on success, FALSE otherwise.
*/
private function addBodyElementIfMissing(): bool
{
Expand All @@ -280,10 +280,10 @@ private function addBodyElementIfMissing(): bool
}

/**
* Dumps the internal document into a string using HTML formatting
* Dumps the internal document into a string using HTML formatting.
*
* @param \DOMNode $node Optional parameter to output a subset of the document.
* @return string The document (or node) HTML code as string
* @return string The document (or node) HTML code as string.
*/
public function saveHTML(\DOMNode $node = null): string
{
Expand Down Expand Up @@ -387,9 +387,10 @@ public function saveHTML(\DOMNode $node = null): string
}

/**
* Dumps the internal document into a file using HTML formatting
* Dumps the internal document into a file using HTML formatting.
*
* @param string $filename The path to the saved HTML document.
* @return int the number of bytes written or FALSE if an error occurred
* @return int the number of bytes written or FALSE if an error occurred.
*/
public function saveHTMLFile($filename)
{
Expand All @@ -406,10 +407,10 @@ public function saveHTMLFile($filename)
}

/**
* Returns the first document element matching the selector
* Returns the first document element matching the selector.
*
* @param string $selector CSS query selector
* @return \DOMElement|null The result DOMElement or null if not found
* @param string $selector A CSS query selector. Available values: *, tagname, tagname#id, #id, tagname.classname, .classname, tagname[attribute-selector] and [attribute-selector].
* @return \DOMElement|null The result DOMElement or null if not found.
* @throws \InvalidArgumentException
*/
public function querySelector(string $selector)
Expand All @@ -418,10 +419,10 @@ public function querySelector(string $selector)
}

/**
* Returns a list of document elements matching the selector
* Returns a list of document elements matching the selector.
*
* @param string $selector CSS query selector
* @return \DOMNodeList Returns a list of DOMElements matching the criteria
* @param string $selector A CSS query selector. Available values: *, tagname, tagname#id, #id, tagname.classname, .classname, tagname[attribute-selector] and [attribute-selector].
* @return \DOMNodeList Returns a list of DOMElements matching the criteria.
* @throws \InvalidArgumentException
*/
public function querySelectorAll(string $selector)
Expand All @@ -430,10 +431,10 @@ public function querySelectorAll(string $selector)
}

/**
* Creates an element that will be replaced by the new body in insertHTML
* Creates an element that will be replaced by the new body in insertHTML.
*
* @param string $name The name of the insert target
* @return \DOMElement A new DOMElement that must be set in the place where the new body will be inserted
* @param string $name The name of the insert target.
* @return \DOMElement A new DOMElement that must be set in the place where the new body will be inserted.
*/
public function createInsertTarget(string $name)
{
Expand All @@ -448,7 +449,7 @@ public function createInsertTarget(string $name)
/**
* Inserts a HTML document into the current document. The elements from the head and the body will be moved to their proper locations.
*
* @param string $source The HTML code to be inserted
* @param string $source The HTML code to be inserted.
* @param string $target Body target position. Available values: afterBodyBegin, beforeBodyEnd or insertTarget name.
*/
public function insertHTML(string $source, string $target = 'beforeBodyEnd')
Expand Down Expand Up @@ -749,6 +750,7 @@ private function removeDuplicateMetatags()

/**
* Returns and associative array containing the id of an element and potential occurrences.
*
* @param string $html
*/
private function getPotentialElementsIDs($html)
Expand All @@ -760,6 +762,7 @@ private function getPotentialElementsIDs($html)

/**
* Moves the title element and the metatags first
*
* @param \DOMElement $headElement
*/
private function optimizeHeadElementsOrder(&$headElement)
Expand Down
12 changes: 6 additions & 6 deletions src/HTML5DOMDocument/Internal/QuerySelectors.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ trait QuerySelectors
{

/**
* Returns the first element matching the selector
* Returns the first element matching the selector.
*
* @param string $selector CSS query selector
* @param string $selector A CSS query selector. Available values: *, tagname, tagname#id, #id, tagname.classname, .classname, tagname[attribute-selector] and [attribute-selector].
* @return \DOMElement|null The result DOMElement or null if not found
*/
private function internalQuerySelector(string $selector)
Expand All @@ -18,11 +18,11 @@ private function internalQuerySelector(string $selector)
}

/**
* Returns a list of document elements matching the selector
* Returns a list of document elements matching the selector.
*
* @param string $selector CSS query selector
* @param int|null $preferredLimit Preferred maximum number of elements to return
* @return DOMNodeList Returns a list of DOMElements matching the criteria
* @param string $selector A CSS query selector. Available values: *, tagname, tagname#id, #id, tagname.classname, .classname, tagname[attribute-selector] and [attribute-selector].
* @param int|null $preferredLimit Preferred maximum number of elements to return.
* @return DOMNodeList Returns a list of DOMElements matching the criteria.
* @throws \InvalidArgumentException
*/
private function internalQuerySelectorAll(string $selector, $preferredLimit = null)
Expand Down
44 changes: 23 additions & 21 deletions src/HTML5DOMElement.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,11 @@
namespace IvoPetkov;

/**
* @property string $innerHTML The HTML code inside the element
* @property string $outerHTML The HTML code for the element including the code inside
* @property \IvoPetkov\HTML5DOMTokenList $classList A collection of the class attributes of the element
* Represents a live (can be manipulated) representation of an element in a HTML5 document.
*
* @property string $innerHTML The HTML code inside the element.
* @property string $outerHTML The HTML code for the element including the code inside.
* @property \IvoPetkov\HTML5DOMTokenList $classList A collection of the class attributes of the element.
*/
class HTML5DOMElement extends \DOMElement
{
Expand All @@ -38,10 +40,10 @@ class HTML5DOMElement extends \DOMElement
private $classList = null;

/**
* Returns the value for the property specified
* Returns the value for the property specified.
*
* @param string $name The name of the property
* @return string The value of the property specified
* @param string $name
* @return string
* @throws \Exception
*/
public function __get(string $name)
Expand Down Expand Up @@ -79,7 +81,7 @@ public function __get(string $name)
}

/**
* Sets the value for the property specified
* Sets the value for the property specified.
*
* @param string $name
* @param string $value
Expand Down Expand Up @@ -121,7 +123,7 @@ public function __set(string $name, $value)
}

/**
* Updates the result value before returning it
* Updates the result value before returning it.
*
* @param string $value
* @return string The updated value
Expand Down Expand Up @@ -151,10 +153,10 @@ private function updateResult(string $value): string
}

/**
* Returns the value for the attribute name specified
* Returns the value for the attribute name specified.
*
* @param string $name The attribute name
* @return string
* @param string $name The attribute name.
* @return string The attribute value.
* @throws \InvalidArgumentException
*/
public function getAttribute($name): string
Expand All @@ -167,9 +169,9 @@ public function getAttribute($name): string
}

/**
* Returns an array containing all attributes
* Returns an array containing all attributes.
*
* @return array An associative array containing all attributes
* @return array An associative array containing all attributes.
*/
public function getAttributes(): array
{
Expand All @@ -182,20 +184,20 @@ public function getAttributes(): array
}

/**
* Returns the element outerHTML
* Returns the element outerHTML.
*
* @return string The element outerHTML
* @return string The element outerHTML.
*/
public function __toString(): string
{
return $this->outerHTML;
}

/**
* Returns the first child element matching the selector
* Returns the first child element matching the selector.
*
* @param string $selector CSS query selector
* @return \DOMElement|null The result DOMElement or null if not found
* @param string $selector A CSS query selector. Available values: *, tagname, tagname#id, #id, tagname.classname, .classname, tagname[attribute-selector] and [attribute-selector].
* @return \DOMElement|null The result DOMElement or null if not found.
* @throws \InvalidArgumentException
*/
public function querySelector(string $selector)
Expand All @@ -204,10 +206,10 @@ public function querySelector(string $selector)
}

/**
* Returns a list of children elements matching the selector
* Returns a list of children elements matching the selector.
*
* @param string $selector CSS query selector
* @return \DOMNodeList Returns a list of DOMElements matching the criteria
* @param string $selector A CSS query selector. Available values: *, tagname, tagname#id, #id, tagname.classname, .classname, tagname[attribute-selector] and [attribute-selector].
* @return \DOMNodeList Returns a list of DOMElements matching the criteria.
* @throws \InvalidArgumentException
*/
public function querySelectorAll(string $selector)
Expand Down
12 changes: 7 additions & 5 deletions src/HTML5DOMNodeList.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,28 @@
namespace IvoPetkov;

/**
* Represents a list of DOM nodes.
*
* @property-read int $length The list items count
*/
class HTML5DOMNodeList extends \ArrayObject
{

/**
* Returns the item at the specified index
* Returns the item at the specified index.
*
* @param int $index The item index
* @return \IvoPetkov\HTML5DOMElement|null The item at the specified index or null if not existent
* @param int $index The item index.
* @return \IvoPetkov\HTML5DOMElement|null The item at the specified index or null if not existent.
*/
public function item(int $index)
{
return $this->offsetExists($index) ? $this->offsetGet($index) : null;
}

/**
* Returns the value for the property specified
* Returns the value for the property specified.
*
* @param string $name The name of the property
* @param string $name The name of the property.
* @return mixed
* @throws \Exception
*/
Expand Down
Loading

0 comments on commit 5ff1c48

Please sign in to comment.