Added getters for Serializer options;

Swapped the indent and indent string options at Serializer's constructor;
Renamed Serializer::setIndentFirstLine() to setIsFirstLineIndented() in accordance with the getter (PHPMD fix);
Line length is now ACTUALLY line length, i.e. it takes the indentation into account, and is applied to tags as well;
Fixed ReturnTag::setContent() to set "types" to NULL;
A lot of doc and CS fixes at Serializer.php.

src/phpDocumentor/Reflection/DocBlock.php

@@ -229,24 +229,38 @@ class DocBlock implements \Reflector
         $this->tags = $result;
     }
 
-    public function getText(){
+    /**
+     * Gets the text portion of the doc block.
+     * 
+     * Gets the text portion (short and long description combined) of the doc
+     * block.
+     * 
+     * @return string The text portion of the doc block.
+     */
+    public function getText()
+    {
         $short = $this->getShortDescription();
         $long = $this->getLongDescription()->getContents();
 
-        if($long){
+        if ($long) {
             return $short . "\n\n" . $long;
-        }else{
+        } else {
             return $short;
         }
     }
 
     /**
-     * Set the short and long description.
+     * Set the text portion of the doc block.
      * 
-     * @param string $docblock
+     * Sets the text portion (short and long description combined) of the doc
-     * @return $this
+     * block.
+     *
+     * @param string $docblock The new text portion of the doc block.
+     * 
+     * @return $this This doc block.
      */
-    public function setText($comment){
+    public function setText($comment)
+    {
         list($short, $long) = $this->splitDocBlock($comment);
         $this->short_description = $short;
         $this->long_description = new DocBlock\Description($long, $this);

src/phpDocumentor/Reflection/DocBlock/Serializer.php

@@ -4,8 +4,8 @@
  *
  * PHP Version 5.3
  *
- * @author    Mike van Riel <mike.vanriel@naenius.com>
+ * @author    Barry vd. Heuvel <barryvdh@gmail.com>
- * @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
+ * @copyright 2013 Mike van Riel / Naenius (http://www.naenius.com)
  * @license   http://www.opensource.org/licenses/mit-license.php MIT
  * @link      http://phpdoc.org
  */
@@ -15,7 +15,7 @@ namespace phpDocumentor\Reflection\DocBlock;
 use phpDocumentor\Reflection\DocBlock;
 
 /**
- * Serializes a DocBlock instance
+ * Serializes a DocBlock instance.
  *
  * @author  Barry vd. Heuvel <[email protected]>
  * @license http://www.opensource.org/licenses/mit-license.php MIT
@@ -24,98 +24,185 @@ use phpDocumentor\Reflection\DocBlock;
 class Serializer
 {
 
-    /** @var string The string to indent the comment with */
+    /** @var string The string to indent the comment with. */
-    protected $indentString;
+    protected $indentString = ' ';
 
-    /** @var  int The number of times $indentString is repeated */
+    /** @var int The number of times the indent string is repeated. */
-    protected $indent;
+    protected $indent = 0;
 
-    /** @var  bool Indent the first line */
+    /** @var bool Whether to indent the first line. */
-    protected $indentFirstLine;
+    protected $isFirstLineIndented = true;
 
-    /** @var int The max length of a description line. */
+    /** @var int The max length of a line. */
     protected $lineLength = null;
 
     /**
      * Create a Serializer instance.
      *
-     * @param string $indentString
+     * @param int    $indent          The number of times the indent string is
-     * @param int $indent
+     *     repeated.
-     * @param bool $indentFirstLine
+     * @param string $indentString    The string to indent the comment with.
-     * @internal param string $indentationString The indentation string.
+     * @param bool   $indentFirstLine Whether to indent the first line.
+     * @param int    $lineLength      The max length of a line.
      */
-    public function __construct($indentString = ' ', $indent = 4, $indentFirstLine = true)
+    public function __construct(
-    {
+        $indent = 0,
-        $this->indentString = $indentString;
+        $indentString = ' ',
-        $this->indent = $indent;
+        $indentFirstLine = true,
-        $this->indentFirstLine = $indentFirstLine;
+        $lineLength = null
+    ) {
+        $this->setIndentationString($indentString);
+        $this->setIndent($indent);
+        $this->setIsFirstLineIndented($indentFirstLine);
+        $this->setLineLength($lineLength);
     }
 
     /**
-     * @param $indentationString
+     * Sets the string to indent comments with.
-     * @return $this
-     */
-    public function setIndentationString($indentationString)
-    {
-        $this->indentation = $indentationString;
-        return $this;
-    }
-
-    /**
-     * @param $indent
-     * @return $this
-     */
-    public function setIndent($indent){
-        $this->indent = $indent;
-        return $this;
-    }
-
-    /**
-     * @param $indentFirstLine
-     * @return $this
-     */
-    public function setIndentFirstLine($indentFirstLine){
-        $this->indentFirstLine = $indentFirstLine;
-        return $this;
-    }
-
-    /**
-     * @param $lineLength
-     * @return $this
-     */
-    public function setLineLength($lineLength){
-        $this->lineLength = $lineLength;
-        return $this;
-    }
-
-    /**
-     * Generate a DocBlock Comment
      * 
-     * @param DocBlock  The DocBlock to serialize
+     * @param string $indentationString The string to indent comments with.
-     * @return string
+     * 
+     * @return $this This serializer object.
      */
-    public function getDocComment($phpdoc){
+    public function setIndentationString($indentString)
+    {
+        $this->indentString = (string)$indentString;
+        return $this;
+    }
 
-        $indent = '';
+    /**
-        for($i=0;$i<$this->indent;$i++){
+     * Gets the string to indent comments with.
-            $indent .= $this->indentString;
+     * 
+     * @return string The indent string.
+     */
+    public function getIndentationString()
+    {
+        return $this->indentString;
+    }
+
+    /**
+     * Sets the number of indents.
+     * 
+     * @param int $indent The number of times the indent string is repeated.
+     * 
+     * @return $this This serializer object.
+     */
+    public function setIndent($indent)
+    {
+        $this->indent = (int)$indent;
+        return $this;
+    }
+
+    /**
+     * Gets the number of indents.
+     * 
+     * @return int The number of times the indent string is repeated.
+     */
+    public function getIndent()
+    {
+        return $this->indent;
+    }
+
+    /**
+     * Sets whether or not the first line should be indented.
+     * 
+     * Sets whether or not the first line (the one with the "/**") should be
+     * indented.
+     * 
+     * @param bool $indentFirstLine The new value for this setting.
+     * 
+     * @return $this This serializer object.
+     */
+    public function setIsFirstLineIndented($indentFirstLine)
+    {
+        $this->isFirstLineIndented = (bool)$indentFirstLine;
+        return $this;
+    }
+
+    /**
+     * Gets whether or not the first line should be indented.
+     * 
+     * @return bool Whether or not the first line should be indented.
+     */
+    public function isFirstLineIndented()
+    {
+        return $this->isFirstLineIndented;
+    }
+
+    /**
+     * Sets the line length.
+     * 
+     * Sets the length of each line in the serialization. Content will be
+     * wrapped within this limit.
+     * 
+     * @param int $lineLength The length of each line. NULL to disable line
+     *     wrapping altogether.
+     * 
+     * @return $this This serializer object.
+     */
+    public function setLineLength($lineLength)
+    {
+        $this->lineLength = null === $lineLength ? null : (int)$lineLength;
+        return $this;
+    }
+
+    /**
+     * Gets the line length.
+     * 
+     * @return int The length of each line or NULL if line wrapping is disabled.
+     */
+    public function getLineLength()
+    {
+        return $this->lineLength;
+    }
+
+    /**
+     * Generate a DocBlock comment.
+     *
+     * @param DocBlock The DocBlock to serialize.
+     * 
+     * @return string The serialized doc block.
+     */
+    public function getDocComment(DocBlock $docblock)
+    {
+        $indent = str_repeat($this->indentString, $this->indent);
+        $firstIndent = $this->isFirstLineIndented ? $indent : '';
+
+        $text = $docblock->getText();
+        if ($this->lineLength) {
+            $text = wordwrap(
+                $text,
+                $this->lineLength - strlen($indent) - 3/*strlen(' * ')*/
+            );
         }
-        $firstIndent = $this->indentFirstLine ? $indent : '';
+        $text = str_replace("\n", "\n$indent * ", $text);
 
-        $description = $phpdoc->getText();
+        $comment = "$firstIndent/**\n$indent * $text\n$indent *\n";
-        if($this->lineLength){
-            $description = wordwrap($description, $this->lineLength);
-        }
-        $description = str_replace("\n", "\n$indent * ", $description);
-
-        $comment = "$firstIndent/**\n$indent * $description\n$indent *\n";
 
         /** @var Tag $tag */
-        foreach ($phpdoc->getTags() as $tag) {
+        foreach ($docblock->getTags() as $tag) {
-            $comment .= $indent.' * @'. $tag->getName() . " " . $tag->getContent() . "\n";
+            $tagName = $tag->getName();
+            $prefixLength = 1/*strlen('@')*/ + strlen($tagName);
+
+            //Added to take the first line of the tag into account.
+            $tagContent = str_repeat(' ', $prefixLength) . $tag->getContent();
+
+            if ($this->lineLength) {
+                $tagContent = wordwrap(
+                    $tagContent,
+                    $this->lineLength - strlen($indent) - 3/*strlen(' * ')*/
+                );
+            }
+
+            //Clean up the prefix.
+            substr_replace($tagContent, '', 0, $prefixLength);
+
+            $tagContent = str_replace("\n", "\n$indent * ", $tagContent);
+
+            $comment .= "$indent * @{$tagName} {$tagContent}\n";
         }
 
-        $comment .= $indent.' */';
+        $comment .= $indent . ' */';
 
         return $comment;
     }

src/phpDocumentor/Reflection/DocBlock/Tag/ReturnTag.php

@@ -53,6 +53,7 @@ class ReturnTag extends Tag
 
         // any output is considered a type
         $this->type = $parts[0];
+        $this->types = null;
 
         $this->setDescription(isset($parts[1]) ? $parts[1] : '');