Merge branch 'master' into 1.0

Conflicts: src/Ciconia/Ciconia.php
kzykhys · Dec 11, 2013 · add01eb · add01eb
2 parents 7067efd + 615dddb
commit add01eb
Show file tree

Hide file tree

Showing 14 changed files with 151 additions and 68 deletions.
diff --git a/composer.json b/composer.json
@@ -27,7 +27,7 @@
     "bin": ["bin/ciconia"],
     "extra": {
         "branch-alias": {
-            "dev-master": "1.0.x-dev"
+            "dev-master": "1.1.x-dev"
         }
     }
 }
diff --git a/src/Ciconia/Common/Collection.php b/src/Ciconia/Common/Collection.php
@@ -14,6 +14,8 @@ class Collection implements \IteratorAggregate, \Countable
     private $objects;
 
     /**
+     * Constructor
+     *
      * @param array $objects [optional]
      */
     public function __construct(array $objects = array())
@@ -24,7 +26,7 @@ public function __construct(array $objects = array())
     /**
      * Appends a new value as the last element.
      *
-     * @param mixed $object
+     * @param mixed $object The value to append
      *
      * @return Collection
      */
@@ -38,8 +40,8 @@ public function add($object)
     /**
      * Sets the value at the specified index
      *
-     * @param string $name
-     * @param mixed $object
+     * @param string $name   The index
+     * @param mixed  $object The value
      *
      * @return Collection
      */
@@ -53,9 +55,9 @@ public function set($name, $object)
     /**
      * Returns the value at the specified index
      *
-     * @param string $name
+     * @param string $name The index
      *
-     * @throws \OutOfBoundsException
+     * @throws \OutOfBoundsException When the index is invalid
      *
      * @return mixed
      */
@@ -71,9 +73,9 @@ public function get($name)
     /**
      * Returns whether the requested index exists
      *
-     * @param string $name
+     * @param string $name The index
      *
-     * @return bool
+     * @return bool True if the index is valid
      */
     public function exists($name)
     {
@@ -83,19 +85,21 @@ public function exists($name)
     /**
      * Returns whether the requested value exists
      *
-     * @param mixed $object
+     * @param mixed $object The value
      *
-     * @return bool
+     * @return bool True if the value exists
      */
     public function contains($object)
     {
         return array_search($object, $this->objects, true) !== false;
     }
 
     /**
-     * @param $name
+     * Remove
+     *
+     * @param string $name The index
      *
-     * @return $this
+     * @return Collection
      */
     public function remove($name)
     {
@@ -122,11 +126,11 @@ public function join($glue = '')
      * Extract a slice of the array
      *
      * @param integer $offset If offset is non-negative, the sequence will start at that offset in the array.
-     *                         If offset is negative, the sequence will start that far from the end of the array.
+     *                        If offset is negative, the sequence will start that far from the end of the array.
      * @param integer $length If length is given and is positive, then the sequence will have up to that many elements in it.
-     *                         If the array is shorter than the length, then only the available array elements will be present.
-     *                         If length is given and is negative then the sequence will stop that many elements from the end of the array.
-     *                         If it is omitted, then the sequence will have everything from offset up until the end of the array.
+     *                        If the array is shorter than the length, then only the available array elements will be present.
+     *                        If length is given and is negative then the sequence will stop that many elements from the end of the array.
+     *                        If it is omitted, then the sequence will have everything from offset up until the end of the array.
      *
      * @return Collection
      */

diff --git a/src/Ciconia/Common/Tag.php b/src/Ciconia/Common/Tag.php
@@ -3,12 +3,21 @@
 namespace Ciconia\Common;
 
 /**
+ * HTML/XHTML/XML tag definition
+ *
  * @author Kazuyuki Hayashi <hayashi@valnur.net>
  */
 class Tag
 {
 
-    const TYPE_BLOCK  = 'block';
+    /**
+     * Block level tag
+     */
+    const TYPE_BLOCK = 'block';
+
+    /**
+     * Inline level tag
+     */
     const TYPE_INLINE = 'inline';
 
     /**
@@ -37,19 +46,23 @@ class Tag
     private $emptyTagSuffix = '>';
 
     /**
+     * Constructor
+     *
      * @param string $name The name of the tag
      */
     public function __construct($name)
     {
-        $this->name = $name;
+        $this->name       = $name;
         $this->attributes = new Collection();
-        $this->text = new Text();
+        $this->text       = new Text();
     }
 
     /**
-     * @param \Ciconia\Common\Text|string $text
+     * Sets the inner text
      *
-     * @return $this
+     * @param Text|string $text A string to set
+     *
+     * @return Tag
      */
     public function setText($text)
     {
@@ -63,15 +76,19 @@ public function setText($text)
     }
 
     /**
-     * @return \Ciconia\Common\Text
+     * Gets the inner text
+     *
+     * @return Text
      */
     public function getText()
     {
         return $this->text;
     }
 
     /**
-     * @param string $name
+     * Sets the name of the tag
+     *
+     * @param string $name The name of the tag
      *
      * @return $this
      */
@@ -83,6 +100,8 @@ public function setName($name)
     }
 
     /**
+     * Returns the name of the tag
+     *
      * @return string
      */
     public function getName()
@@ -91,9 +110,11 @@ public function getName()
     }
 
     /**
-     * @param string $emptyTagSuffix
+     * Sets the empty tag suffix
      *
-     * @return $this
+     * @param string $emptyTagSuffix The suffix
+     *
+     * @return Tag
      */
     public function setEmptyTagSuffix($emptyTagSuffix)
     {
@@ -103,17 +124,21 @@ public function setEmptyTagSuffix($emptyTagSuffix)
     }
 
     /**
-     * @return string
+     * Returns the empty tag suffix
+     *
+     * @return string The suffix
      */
     public function getEmptyTagSuffix()
     {
         return $this->emptyTagSuffix;
     }
 
     /**
-     * @param string $type
+     * Sets the type of the tag (Tag::TYPE_BLOCK or Tag::TYPE_INLINE)
      *
-     * @return $this
+     * @param string $type The type of the tag
+     *
+     * @return Tag
      */
     public function setType($type)
     {
@@ -123,6 +148,8 @@ public function setType($type)
     }
 
     /**
+     * Returns the type of the tag
+     *
      * @return string
      */
     public function getType()
@@ -131,10 +158,12 @@ public function getType()
     }
 
     /**
-     * @param $attribute
-     * @param $value
+     * Sets an attribute
      *
-     * @return $this
+     * @param string $attribute The name of an attribute
+     * @param string $value     [optional] The value of an attribute
+     *
+     * @return Tag
      */
     public function setAttribute($attribute, $value = null)
     {
@@ -144,8 +173,11 @@ public function setAttribute($attribute, $value = null)
     }
 
     /**
-     * @param array $attributes
-     * @return $this
+     * Sets attributes
+     *
+     * @param array $attributes An array of attributes
+     *
+     * @return Tag
      */
     public function setAttributes(array $attributes)
     {
@@ -157,6 +189,8 @@ public function setAttributes(array $attributes)
     }
 
     /**
+     * Returns a collection of attributes
+     *
      * @return Collection
      */
     public function getAttributes()
@@ -165,7 +199,9 @@ public function getAttributes()
     }
 
     /**
-     * @return string
+     * Renders the tag
+     *
+     * @return string The HTML string
      */
     public function render()
     {
@@ -185,13 +221,13 @@ public function render()
 
         if ($this->text->isEmpty()) {
             if ($this->type == self::TYPE_BLOCK) {
-                return (string) $html->append('>')->append('</')->append($this->getName())->append('>');
+                return (string)$html->append('>')->append('</')->append($this->getName())->append('>');
             } else {
-                return (string) $html->append($this->emptyTagSuffix);
+                return (string)$html->append($this->emptyTagSuffix);
             }
         }
 
-        return (string) $html
+        return (string)$html
             ->append('>')
             ->append($this->text)
             ->append('</')

diff --git a/src/Ciconia/Common/Text.php b/src/Ciconia/Common/Text.php
@@ -127,13 +127,15 @@ public function rtrim($charList = null)
      */
     public function isEmpty()
     {
-        return empty($this->text);
+        return $this->text === '';
     }
 
     /**
-     * @param $text
+     * Checks whether the text contains $text
      *
-     * @return bool
+     * @param string $text A string to test
+     *
+     * @return bool True if the text contains $text
      */
     public function contains($text)
     {
@@ -159,7 +161,7 @@ public function escapeHtml($option = ENT_QUOTES)
      *
      * @param string          $pattern     The pattern to search for. It can be either a string or an array with strings.
      * @param string|callable $replacement The string or an array with strings to replace.
-     *                                      If $replacement is the callable, a callback that will be called and passed an array of matched elements in the subject string.
+     *                                     If $replacement is the callable, a callback that will be called and passed an array of matched elements in the subject string.
      *
      * @return Text
      */
@@ -198,8 +200,8 @@ public function replaceString($search, $replace)
     /**
      * Perform a regular expression match
      *
-     * @param string      $pattern The pattern to search for, as a string.
-     * @param array|null  $matches If matches is provided, then it is filled with the results of search.
+     * @param string     $pattern The pattern to search for, as a string.
+     * @param array|null $matches If matches is provided, then it is filled with the results of search.
      *
      * @return boolean
      */
@@ -229,7 +231,7 @@ public function split($pattern, $flags = PREG_SPLIT_DELIM_CAPTURE)
      * Gets the length of a string
      *
      * @return int Returns the number of characters in string str having character encoding encoding.
-     *              A multi-byte character is counted as 1.
+     *             A multi-byte character is counted as 1.
      */
     public function getLength()
     {

diff --git a/src/Ciconia/Console/Command/CiconiaCommand.php b/src/Ciconia/Console/Command/CiconiaCommand.php
@@ -86,9 +86,9 @@ protected function execute(InputInterface $input, OutputInterface $output)
     }
 
     /**
-     * Get markdown content from input
+     * Get a markdown content from input
      *
-     * Warning: Reading from STDIN always fails on Windows
+     * __Warning: Reading from STDIN always fails on Windows__
      *
      * @param InputInterface $input
      *
@@ -127,7 +127,9 @@ protected function handleInput(InputInterface $input)
     }
 
     /**
-     * @param InputInterface $input
+     * Creates an instance of Ciconia
+     *
+     * @param InputInterface $input The InputInterface instance
      *
      * @return Ciconia|\Ciconia\Diagnose\Ciconia
      */
@@ -160,8 +162,8 @@ protected function createCiconia(InputInterface $input)
     /**
      * Runs help command
      *
-     * @param InputInterface  $input
-     * @param OutputInterface $output
+     * @param InputInterface  $input  The InputInterface instance
+     * @param OutputInterface $output The OutputInterface instance
      *
      * @return int
      */
@@ -176,9 +178,9 @@ protected function runHelp(InputInterface $input, OutputInterface $output)
     /**
      * Lints the content
      *
-     * @param OutputInterface $output
-     * @param Ciconia         $ciconia
-     * @param                 $content
+     * @param OutputInterface $output  The OutputInterface instance
+     * @param Ciconia         $ciconia The Ciconia instance
+     * @param string          $content The markdown content
      *
      * @return int
      */