From c7095e630d1da8e3d25905ababea0808ad3d8f12 Mon Sep 17 00:00:00 2001
From: Matt Farina <matt@mattfarina.com>
Date: Wed, 6 Nov 2013 07:56:35 -0500
Subject: Improving the documentation coverage.

---
 src/HTML5.php                          | 25 ++++++++++++++++++++++---
 src/HTML5/Elements.php                 | 11 +++++++++--
 src/HTML5/Parser/StringInputStream.php |  3 +++
 3 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/src/HTML5.php b/src/HTML5.php
index ce0927f..7295fb4 100644
--- a/src/HTML5.php
+++ b/src/HTML5.php
@@ -1,5 +1,7 @@
 <?php
-
+/**
+ * The main HTML5 front end.
+ */
 use HTML5\Parser\StringInputStream;
 use HTML5\Parser\FileInputStream;
 use HTML5\Parser\Scanner;
@@ -9,8 +11,6 @@ use HTML5\Serializer\OutputRules;
 use HTML5\Serializer\Traverser;
 
 /**
- * The main HTML5 front end.
- *
  * This class offers convenience methods for parsing and serializing HTML5.
  * It is roughly designed to mirror the \DOMDocument class that is 
  * provided with most versions of PHP.
@@ -19,6 +19,10 @@ use HTML5\Serializer\Traverser;
  */
 class HTML5 {
 
+  /**
+   * Global options for the parser and serializer.
+   * @var array
+   */
   public static $options = array(
 
     // If the serializer should encode all entities.
@@ -77,6 +81,15 @@ class HTML5 {
    *
    * This is here to provide backwards compatibility with the
    * PHP DOM implementation. It simply calls load().
+   *
+   * @param string $file
+   *   The path to the file to parse. If this is a resource, it is 
+   *   assumed to be an open stream whose pointer is set to the first 
+   *   byte of input.
+   *
+   * @return \DOMDocument
+   *   A DOM document. These object type is defined by the libxml 
+   *   library, and should have been included with your version of PHP.
    */
   public static function loadHTMLFile($file, $options = NULL) {
     return static::load($file, $options);
@@ -166,6 +179,12 @@ class HTML5 {
     return $events->document();
   }
 
+  /**
+   * Parse an input stream where the stream is a fragment.
+   *
+   * Lower-level loading function. This requires an input stream instead 
+   * of a string, file, or resource.
+   */
   public static function parseFragment(\HTML5\Parser\InputStream $input) {
     $events = new DOMTreeBuilder(TRUE);
     $scanner = new Scanner($input);
diff --git a/src/HTML5/Elements.php b/src/HTML5/Elements.php
index 0dabc3a..69d3882 100644
--- a/src/HTML5/Elements.php
+++ b/src/HTML5/Elements.php
@@ -1,9 +1,10 @@
 <?php
+/**
+ * Provide general element functions.
+ */
 namespace HTML5;
 
 /**
- * Provide general element functions.
- *
  * This class provides general information about HTML5 elements, 
  * including syntactic and semantic issues. Parsers and serializers can 
  * use this class as a reference point for information about the rules 
@@ -532,6 +533,12 @@ class Elements {
 
   /**
    * Get the element mask for the given element name.
+   *
+   * @param string $name
+   *   The name of the element.
+   *
+   * @return int
+   *   The element mask.
    */
   public static function element($name) {
     if (isset(static::$html5[$name])) {
diff --git a/src/HTML5/Parser/StringInputStream.php b/src/HTML5/Parser/StringInputStream.php
index 0d2a7f3..ca5fee0 100644
--- a/src/HTML5/Parser/StringInputStream.php
+++ b/src/HTML5/Parser/StringInputStream.php
@@ -1,4 +1,7 @@
 <?php
+/**
+ * Loads a string to be parsed.
+ */
 namespace HTML5\Parser;
 
 /*
-- 
cgit v1.2.3