annotate vendor/phpdocumentor/reflection-docblock/src/DocBlock/Serializer.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 7a779792577d
children
rev   line source
Chris@12 1 <?php
Chris@12 2 /**
Chris@12 3 * This file is part of phpDocumentor.
Chris@12 4 *
Chris@12 5 * For the full copyright and license information, please view the LICENSE
Chris@12 6 * file that was distributed with this source code.
Chris@12 7 *
Chris@12 8 * @copyright 2010-2015 Mike van Riel<mike@phpdoc.org>
Chris@12 9 * @license http://www.opensource.org/licenses/mit-license.php MIT
Chris@12 10 * @link http://phpdoc.org
Chris@12 11 */
Chris@12 12
Chris@12 13 namespace phpDocumentor\Reflection\DocBlock;
Chris@12 14
Chris@12 15 use phpDocumentor\Reflection\DocBlock;
Chris@12 16 use Webmozart\Assert\Assert;
Chris@12 17
Chris@12 18 /**
Chris@12 19 * Converts a DocBlock back from an object to a complete DocComment including Asterisks.
Chris@12 20 */
Chris@12 21 class Serializer
Chris@12 22 {
Chris@12 23 /** @var string The string to indent the comment with. */
Chris@12 24 protected $indentString = ' ';
Chris@12 25
Chris@12 26 /** @var int The number of times the indent string is repeated. */
Chris@12 27 protected $indent = 0;
Chris@12 28
Chris@12 29 /** @var bool Whether to indent the first line with the given indent amount and string. */
Chris@12 30 protected $isFirstLineIndented = true;
Chris@12 31
Chris@12 32 /** @var int|null The max length of a line. */
Chris@12 33 protected $lineLength = null;
Chris@12 34
Chris@12 35 /** @var DocBlock\Tags\Formatter A custom tag formatter. */
Chris@12 36 protected $tagFormatter = null;
Chris@12 37
Chris@12 38 /**
Chris@12 39 * Create a Serializer instance.
Chris@12 40 *
Chris@12 41 * @param int $indent The number of times the indent string is repeated.
Chris@12 42 * @param string $indentString The string to indent the comment with.
Chris@12 43 * @param bool $indentFirstLine Whether to indent the first line.
Chris@12 44 * @param int|null $lineLength The max length of a line or NULL to disable line wrapping.
Chris@12 45 * @param DocBlock\Tags\Formatter $tagFormatter A custom tag formatter, defaults to PassthroughFormatter.
Chris@12 46 */
Chris@12 47 public function __construct($indent = 0, $indentString = ' ', $indentFirstLine = true, $lineLength = null, $tagFormatter = null)
Chris@12 48 {
Chris@12 49 Assert::integer($indent);
Chris@12 50 Assert::string($indentString);
Chris@12 51 Assert::boolean($indentFirstLine);
Chris@12 52 Assert::nullOrInteger($lineLength);
Chris@12 53 Assert::nullOrIsInstanceOf($tagFormatter, 'phpDocumentor\Reflection\DocBlock\Tags\Formatter');
Chris@12 54
Chris@12 55 $this->indent = $indent;
Chris@12 56 $this->indentString = $indentString;
Chris@12 57 $this->isFirstLineIndented = $indentFirstLine;
Chris@12 58 $this->lineLength = $lineLength;
Chris@12 59 $this->tagFormatter = $tagFormatter ?: new DocBlock\Tags\Formatter\PassthroughFormatter();
Chris@12 60 }
Chris@12 61
Chris@12 62 /**
Chris@12 63 * Generate a DocBlock comment.
Chris@12 64 *
Chris@12 65 * @param DocBlock $docblock The DocBlock to serialize.
Chris@12 66 *
Chris@12 67 * @return string The serialized doc block.
Chris@12 68 */
Chris@12 69 public function getDocComment(DocBlock $docblock)
Chris@12 70 {
Chris@12 71 $indent = str_repeat($this->indentString, $this->indent);
Chris@12 72 $firstIndent = $this->isFirstLineIndented ? $indent : '';
Chris@12 73 // 3 === strlen(' * ')
Chris@12 74 $wrapLength = $this->lineLength ? $this->lineLength - strlen($indent) - 3 : null;
Chris@12 75
Chris@12 76 $text = $this->removeTrailingSpaces(
Chris@12 77 $indent,
Chris@12 78 $this->addAsterisksForEachLine(
Chris@12 79 $indent,
Chris@12 80 $this->getSummaryAndDescriptionTextBlock($docblock, $wrapLength)
Chris@12 81 )
Chris@12 82 );
Chris@12 83
Chris@12 84 $comment = "{$firstIndent}/**\n";
Chris@12 85 if ($text) {
Chris@12 86 $comment .= "{$indent} * {$text}\n";
Chris@12 87 $comment .= "{$indent} *\n";
Chris@12 88 }
Chris@12 89
Chris@12 90 $comment = $this->addTagBlock($docblock, $wrapLength, $indent, $comment);
Chris@12 91 $comment .= $indent . ' */';
Chris@12 92
Chris@12 93 return $comment;
Chris@12 94 }
Chris@12 95
Chris@12 96 /**
Chris@12 97 * @param $indent
Chris@12 98 * @param $text
Chris@12 99 * @return mixed
Chris@12 100 */
Chris@12 101 private function removeTrailingSpaces($indent, $text)
Chris@12 102 {
Chris@12 103 return str_replace("\n{$indent} * \n", "\n{$indent} *\n", $text);
Chris@12 104 }
Chris@12 105
Chris@12 106 /**
Chris@12 107 * @param $indent
Chris@12 108 * @param $text
Chris@12 109 * @return mixed
Chris@12 110 */
Chris@12 111 private function addAsterisksForEachLine($indent, $text)
Chris@12 112 {
Chris@12 113 return str_replace("\n", "\n{$indent} * ", $text);
Chris@12 114 }
Chris@12 115
Chris@12 116 /**
Chris@12 117 * @param DocBlock $docblock
Chris@12 118 * @param $wrapLength
Chris@12 119 * @return string
Chris@12 120 */
Chris@12 121 private function getSummaryAndDescriptionTextBlock(DocBlock $docblock, $wrapLength)
Chris@12 122 {
Chris@12 123 $text = $docblock->getSummary() . ((string)$docblock->getDescription() ? "\n\n" . $docblock->getDescription()
Chris@12 124 : '');
Chris@12 125 if ($wrapLength !== null) {
Chris@12 126 $text = wordwrap($text, $wrapLength);
Chris@12 127 return $text;
Chris@12 128 }
Chris@12 129
Chris@12 130 return $text;
Chris@12 131 }
Chris@12 132
Chris@12 133 /**
Chris@12 134 * @param DocBlock $docblock
Chris@12 135 * @param $wrapLength
Chris@12 136 * @param $indent
Chris@12 137 * @param $comment
Chris@12 138 * @return string
Chris@12 139 */
Chris@12 140 private function addTagBlock(DocBlock $docblock, $wrapLength, $indent, $comment)
Chris@12 141 {
Chris@12 142 foreach ($docblock->getTags() as $tag) {
Chris@12 143 $tagText = $this->tagFormatter->format($tag);
Chris@12 144 if ($wrapLength !== null) {
Chris@12 145 $tagText = wordwrap($tagText, $wrapLength);
Chris@12 146 }
Chris@12 147
Chris@12 148 $tagText = str_replace("\n", "\n{$indent} * ", $tagText);
Chris@12 149
Chris@12 150 $comment .= "{$indent} * {$tagText}\n";
Chris@12 151 }
Chris@12 152
Chris@12 153 return $comment;
Chris@12 154 }
Chris@12 155 }