Update and fix docblocks

src/Container.php

@@ -28,22 +28,23 @@
 class Container
 {
     /**
-     * @var PartBuilderFactory
+     * @var PartBuilderFactory The PartBuilderFactory instance
      */
     protected $partBuilderFactory;
 
     /**
-     * @var PartFactoryService
+     * @var PartFactoryService The PartFactoryService instance
      */
     protected $partFactoryService;
 
     /**
-     * @var PartFilterFactory
+     * @var PartFilterFactory The PartFilterFactory instance
      */
     protected $partFilterFactory;
 
     /**
-     * @var PartStreamFilterManagerFactory
+     * @var PartStreamFilterManagerFactory The PartStreamFilterManagerFactory
+     *      instance
      */
     protected $partStreamFilterManagerFactory;
 

src/Header/Consumer/ConsumerService.php

@@ -32,6 +32,7 @@ class ConsumerService
      * Sets up the HeaderPartFactory member variable.
      * 
      * @param HeaderPartFactory $partFactory
+     * @param MimeLiteralPartFactory $mimeLiteralPartFactory
      */
     public function __construct(HeaderPartFactory $partFactory, MimeLiteralPartFactory $mimeLiteralPartFactory)
     {

src/Header/Consumer/ParameterConsumer.php

@@ -114,7 +114,8 @@ private function getPartFor($strName, $strValue, ArrayObject $splitParts)
      * Returns true if the token was processed, and false otherwise.
      * 
      * @param string $tokenValue
-     * @param array $combined
+     * @param ArrayObject $combined
+     * @param ArrayObject $splitParts
      * @param string $strName
      * @param string $strCat
      * @return boolean

src/Header/HeaderContainer.php

@@ -52,6 +52,8 @@ class HeaderContainer implements IteratorAggregate
     private $nextIndex = 0;
 
     /**
+     * Constructor
+     *
      * @param HeaderFactory $headerFactory
      */
     public function __construct(HeaderFactory $headerFactory)

src/MailMimeParser.php

@@ -34,6 +34,9 @@ class MailMimeParser
 
     /**
      * Sets up the parser.
+     *
+     * @param Container $di pass a Container object to use it for
+     *        initialization.
      */
     public function __construct(Container $di = null)
     {

src/Message.php

@@ -33,6 +33,8 @@ class Message extends MimePart
     protected $messageHelperService;
 
     /**
+     * Constructor
+     *
      * @param PartStreamFilterManager $partStreamFilterManager
      * @param StreamFactory $streamFactory
      * @param PartFilterFactory $partFilterFactory
@@ -343,6 +345,7 @@ public function setHtmlPart($resource, $charset = 'UTF-8')
      * Removes the text/plain part of the message at the passed index if one
      * exists.  Returns true on success.
      *
+     * @param int $index
      * @return bool true on success
      */
     public function removeTextPart($index = 0)
@@ -375,6 +378,7 @@ public function removeAllTextParts($keepOtherPartsAsAttachments = true)
      * Removes the html part of the message if one exists.  Returns true on
      * success.
      *
+     * @param int $index
      * @return bool true on success
      */
     public function removeHtmlPart($index = 0)

src/Message/Helper/AbstractHelper.php

@@ -33,6 +33,8 @@ abstract class AbstractHelper
     protected $partBuilderFactory;
 
     /**
+     * Constructor
+     * 
      * @param MimePartFactory $mimePartFactory
      * @param UUEncodedPartFactory $uuEncodedPartFactory
      * @param PartBuilderFactory $partBuilderFactory

src/Message/Helper/GenericHelper.php

@@ -79,6 +79,7 @@ public function removeContentHeadersAndContent(ParentHeaderPart $part)
      *
      * @param ParentHeaderPart $from
      * @param ParentHeaderPart $to
+     * @param bool $move
      */
     public function copyContentHeadersAndContent(ParentHeaderPart $from, ParentHeaderPart $to, $move = false)
     {
@@ -141,6 +142,7 @@ public function movePartContentAndChildren(ParentHeaderPart $from, ParentHeaderP
      * replaced, and instead $replacement's type headers are copied to $message,
      * and any children below $replacement are added directly below $message.
      *
+     * @param Message $message
      * @param ParentHeaderPart $part
      * @param ParentHeaderPart $replacement
      */

src/Message/Helper/MessageHelperService.php

@@ -17,7 +17,7 @@
 class MessageHelperService
 {
     /**
-     * @var PartBuilderFactory
+     * @var PartBuilderFactory the PartBuilderFactory
      */
     private $partBuilderFactory;
 
@@ -42,6 +42,8 @@ class MessageHelperService
     private $partFactoryService;
 
     /**
+     * Constructor
+     *
      * @param PartBuilderFactory $partBuilderFactory
      */
     public function __construct(PartBuilderFactory $partBuilderFactory)

src/Message/Helper/MultipartHelper.php

@@ -30,6 +30,8 @@ class MultipartHelper extends AbstractHelper
     private $genericHelper;
 
     /**
+     * Constructor
+     * 
      * @param MimePartFactory $mimePartFactory
      * @param UUEncodedPartFactory $uuEncodedPartFactory
      * @param PartBuilderFactory $partBuilderFactory

src/Message/Helper/PrivacyHelper.php

@@ -31,6 +31,8 @@ class PrivacyHelper extends AbstractHelper
     private $multipartHelper;
 
     /**
+     * Constructor
+     * 
      * @param MimePartFactory $mimePartFactory
      * @param UUEncodedPartFactory $uuEncodedPartFactory
      * @param PartBuilderFactory $partBuilderFactory

src/Message/MessageFactory.php

@@ -28,6 +28,8 @@ class MessageFactory extends MimePartFactory
     protected $messageHelperService;
 
     /**
+     * Constructor
+     * 
      * @param StreamFactory $sdf
      * @param PartStreamFilterManagerFactory $psf
      * @param PartFilterFactory $pf

src/Message/MessageParser.php

@@ -203,7 +203,6 @@ private function readPartContent($handle, PartBuilder $partBuilder)
      * 
      * @param resource $handle
      * @param PartBuilder $partBuilder
-     * @param boolean $isMessage
      */
     protected function readPart($handle, PartBuilder $partBuilder)
     {

src/Message/Part/Factory/MessagePartFactory.php

@@ -32,7 +32,7 @@ abstract class MessagePartFactory
     protected $streamFactory;
 
     /**
-     * @static MessagePartFactory[] cached instances of MessagePartFactory
+     * @var MessagePartFactory[] cached instances of MessagePartFactory
      *      sub-classes
      */
     private static $instances = null;

src/Message/Part/MessagePart.php

@@ -62,6 +62,8 @@ abstract class MessagePart
     protected $ignoreTransferEncoding;
 
     /**
+     * Constructor
+     * 
      * @param PartStreamFilterManager $partStreamFilterManager
      * @param StreamFactory $streamFactory
      * @param StreamInterface $stream
@@ -309,6 +311,7 @@ public function getContentStream($charset = MailMimeParser::DEFAULT_CHARSET)
      * The returned string is encoded to the passed $charset character encoding,
      * defaulting to UTF-8.
      *
+     * @param string $charset
      * @return string
      */
     public function getContent($charset = MailMimeParser::DEFAULT_CHARSET)

src/Message/Part/MimePart.php

@@ -76,7 +76,8 @@ public function isTextPart()
      * 
      * Parses the Content-Type header, defaults to returning text/plain if not
      * defined.
-     * 
+     *
+     * @param string $default pass to override the returned value when not set
      * @return string
      */
     public function getContentType($default = 'text/plain')
@@ -106,7 +107,9 @@ public function getCharset()
 
     /**
      * Returns the content's disposition, defaulting to 'inline' if not set.
-     * 
+     *
+     * @param string $default pass to override the default returned disposition
+     *        when not set.
      * @return string
      */
     public function getContentDisposition($default = 'inline')
@@ -117,7 +120,8 @@ public function getContentDisposition($default = 'inline')
     /**
      * Returns the content-transfer-encoding used for this part, defaulting to
      * '7bit' if not set.
-     * 
+     *
+     * @param string $default pass to override the default when not set.
      * @return string
      */
     public function getContentTransferEncoding($default = '7bit')

src/Message/Part/ParentHeaderPart.php

@@ -20,11 +20,13 @@
 abstract class ParentHeaderPart extends ParentPart
 {
     /**
-     * @var HeaderContainer
+     * @var HeaderContainer Contains headers for this part.
      */
     protected $headerContainer;
 
     /**
+     * Constructor
+     *
      * @param PartStreamFilterManager $partStreamFilterManager
      * @param StreamFactory $streamFactory
      * @param PartFilterFactory $partFilterFactory
@@ -52,11 +54,14 @@ public function __construct(
     }
 
     /**
-     * Returns the AbstractHeader object for the header with the given $name
+     * Returns the AbstractHeader object for the header with the given $name.
+     * If the optional $offset is passed, and multiple headers exist with the
+     * same name, the one at the passed offset is returned.
      *
      * Note that mime headers aren't case sensitive.
      *
      * @param string $name
+     * @param int $offset
      * @return \ZBateson\MailMimeParser\Header\AbstractHeader
      */
     public function getHeader($name, $offset = 0)
@@ -142,13 +147,34 @@ public function getHeaderParameter($header, $param, $defaultValue = null)
     }
 
     /**
-     * Adds a header with the given $name and $value.
-     *
-     * Creates a new \ZBateson\MailMimeParser\Header\AbstractHeader object and
-     * registers it as a header.
+     * Adds a header with the given $name and $value.  An optional $offset may
+     * be passed, which will overwrite a header if one exists with the given
+     * name and offset. Otherwise a new header is added.  The passed $offset may
+     * be ignored in that case if it doesn't represent the next insert position
+     * for the header with the passed name... instead it would be 'pushed' on at
+     * the next position.
+     *
+     * ```php
+     * $part = $myParentHeaderPart;
+     * $part->setRawHeader('New-Header', 'value');
+     * echo $part->getHeaderValue('New-Header');        // 'value'
+     *
+     * $part->setRawHeader('New-Header', 'second', 4);
+     * echo is_null($part->getHeader('New-Header', 4)); // '1' (true)
+     * echo $part->getHeader('New-Header', 1)
+     *      ->getValue();                               // 'second'
+     * ```
+     *
+     * A new \ZBateson\MailMimeParser\Header\AbstractHeader object is created
+     * from the passed value.  No processing on the passed string is performed,
+     * and so the passed name and value must be formatted correctly according to
+     * related RFCs.  In particular, be careful to encode non-ascii data, to
+     * keep lines under 998 characters in length, and to follow any special
+     * formatting required for the type of header.
      *
      * @param string $name
      * @param string $value
+     * @param int $offset
      */
     public function setRawHeader($name, $value, $offset = 0)
     {
@@ -158,6 +184,10 @@ public function setRawHeader($name, $value, $offset = 0)
 
     /**
      * Adds a header with the given $name and $value.
+     * 
+     * Note: If a header with the passed name already exists, a new header is
+     * created with the same name.  This should only be used when that is
+     * intentional - in most cases setRawHeader should be called.
      *
      * Creates a new \ZBateson\MailMimeParser\Header\AbstractHeader object and
      * registers it as a header.
@@ -172,7 +202,7 @@ public function addRawHeader($name, $value)
     }
 
     /**
-     * Removes the header with the given name
+     * Removes all headers from this part with the passed name.
      *
      * @param string $name
      */
@@ -183,7 +213,8 @@ public function removeHeader($name)
     }
 
     /**
-     * Removes the header with the given name
+     * Removes a single header with the passed name (in cases where more than
+     * one may exist, and others should be preserved).
      *
      * @param string $name
      */

src/Message/Part/ParentPart.php

@@ -29,6 +29,8 @@ abstract class ParentPart extends MessagePart
     protected $children = [];
 
     /**
+     * Constructor
+     * 
      * @param PartStreamFilterManager $partStreamFilterManager
      * @param StreamFactory $streamFactory
      * @param PartFilterFactory $partFilterFactory
@@ -181,9 +183,11 @@ public function getChildCount(PartFilter $filter = null)
     }
 
     /**
-     * Returns the part associated with the passed mime type if it exists.
+     * Returns the part associated with the passed mime type, at the passed
+     * index, if it exists.
      *
      * @param string $mimeType
+     * @param int $index
      * @return MessagePart|null
      */
     public function getPartByMimeType($mimeType, $index = 0)

src/Message/Part/UUEncodedPart.php

@@ -37,6 +37,8 @@ class UUEncodedPart extends NonMimePart
     protected $filename = null;
 
     /**
+     * Constructor
+     * 
      * @param PartStreamFilterManager $partStreamFilterManager
      * @param StreamFactory $streamFactory
      * @param PartBuilder $partBuilder

src/Stream/HeaderStream.php

@@ -33,6 +33,8 @@ class HeaderStream implements StreamInterface
     protected $part;
 
     /**
+     * Constructor
+     * 
      * @param MessagePart $part
      */
     public function __construct(MessagePart $part)