You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
152 lines
4.6 KiB
152 lines
4.6 KiB
3 years ago
|
<?php
|
||
|
|
||
|
declare(strict_types=1);
|
||
|
|
||
|
/**
|
||
|
* This file is part of phpDocumentor.
|
||
|
*
|
||
|
* For the full copyright and license information, please view the LICENSE
|
||
|
* file that was distributed with this source code.
|
||
|
*
|
||
|
* @link http://phpdoc.org
|
||
|
*/
|
||
|
|
||
|
namespace phpDocumentor\Reflection\DocBlock;
|
||
|
|
||
|
use phpDocumentor\Reflection\DocBlock;
|
||
|
use phpDocumentor\Reflection\DocBlock\Tags\Formatter;
|
||
|
use phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter;
|
||
|
use function sprintf;
|
||
|
use function str_repeat;
|
||
|
use function str_replace;
|
||
|
use function strlen;
|
||
|
use function wordwrap;
|
||
|
|
||
|
/**
|
||
|
* Converts a DocBlock back from an object to a complete DocComment including Asterisks.
|
||
|
*/
|
||
|
class Serializer
|
||
|
{
|
||
|
/** @var string The string to indent the comment with. */
|
||
|
protected $indentString = ' ';
|
||
|
|
||
|
/** @var int The number of times the indent string is repeated. */
|
||
|
protected $indent = 0;
|
||
|
|
||
|
/** @var bool Whether to indent the first line with the given indent amount and string. */
|
||
|
protected $isFirstLineIndented = true;
|
||
|
|
||
|
/** @var int|null The max length of a line. */
|
||
|
protected $lineLength;
|
||
|
|
||
|
/** @var Formatter A custom tag formatter. */
|
||
|
protected $tagFormatter;
|
||
|
|
||
|
/**
|
||
|
* Create a Serializer instance.
|
||
|
*
|
||
|
* @param int $indent The number of times the indent string is repeated.
|
||
|
* @param string $indentString The string to indent the comment with.
|
||
|
* @param bool $indentFirstLine Whether to indent the first line.
|
||
|
* @param int|null $lineLength The max length of a line or NULL to disable line wrapping.
|
||
|
* @param Formatter $tagFormatter A custom tag formatter, defaults to PassthroughFormatter.
|
||
|
*/
|
||
|
public function __construct(
|
||
|
int $indent = 0,
|
||
|
string $indentString = ' ',
|
||
|
bool $indentFirstLine = true,
|
||
|
?int $lineLength = null,
|
||
|
?Formatter $tagFormatter = null
|
||
|
) {
|
||
|
$this->indent = $indent;
|
||
|
$this->indentString = $indentString;
|
||
|
$this->isFirstLineIndented = $indentFirstLine;
|
||
|
$this->lineLength = $lineLength;
|
||
|
$this->tagFormatter = $tagFormatter ?: new PassthroughFormatter();
|
||
|
}
|
||
|
|
||
|
/**
|
||
|
* Generate a DocBlock comment.
|
||
|
*
|
||
|
* @param DocBlock $docblock The DocBlock to serialize.
|
||
|
*
|
||
|
* @return string The serialized doc block.
|
||
|
*/
|
||
|
public function getDocComment(DocBlock $docblock) : string
|
||
|
{
|
||
|
$indent = str_repeat($this->indentString, $this->indent);
|
||
|
$firstIndent = $this->isFirstLineIndented ? $indent : '';
|
||
|
// 3 === strlen(' * ')
|
||
|
$wrapLength = $this->lineLength ? $this->lineLength - strlen($indent) - 3 : null;
|
||
|
|
||
|
$text = $this->removeTrailingSpaces(
|
||
|
$indent,
|
||
|
$this->addAsterisksForEachLine(
|
||
|
$indent,
|
||
|
$this->getSummaryAndDescriptionTextBlock($docblock, $wrapLength)
|
||
|
)
|
||
|
);
|
||
|
|
||
|
$comment = $firstIndent . "/**\n";
|
||
|
if ($text) {
|
||
|
$comment .= $indent . ' * ' . $text . "\n";
|
||
|
$comment .= $indent . " *\n";
|
||
|
}
|
||
|
|
||
|
$comment = $this->addTagBlock($docblock, $wrapLength, $indent, $comment);
|
||
|
|
||
|
return $comment . $indent . ' */';
|
||
|
}
|
||
|
|
||
|
private function removeTrailingSpaces(string $indent, string $text) : string
|
||
|
{
|
||
|
return str_replace(
|
||
|
sprintf("\n%s * \n", $indent),
|
||
|
sprintf("\n%s *\n", $indent),
|
||
|
$text
|
||
|
);
|
||
|
}
|
||
|
|
||
|
private function addAsterisksForEachLine(string $indent, string $text) : string
|
||
|
{
|
||
|
return str_replace(
|
||
|
"\n",
|
||
|
sprintf("\n%s * ", $indent),
|
||
|
$text
|
||
|
);
|
||
|
}
|
||
|
|
||
|
private function getSummaryAndDescriptionTextBlock(DocBlock $docblock, ?int $wrapLength) : string
|
||
|
{
|
||
|
$text = $docblock->getSummary() . ((string) $docblock->getDescription() ? "\n\n" . $docblock->getDescription()
|
||
|
: '');
|
||
|
if ($wrapLength !== null) {
|
||
|
$text = wordwrap($text, $wrapLength);
|
||
|
|
||
|
return $text;
|
||
|
}
|
||
|
|
||
|
return $text;
|
||
|
}
|
||
|
|
||
|
private function addTagBlock(DocBlock $docblock, ?int $wrapLength, string $indent, string $comment) : string
|
||
|
{
|
||
|
foreach ($docblock->getTags() as $tag) {
|
||
|
$tagText = $this->tagFormatter->format($tag);
|
||
|
if ($wrapLength !== null) {
|
||
|
$tagText = wordwrap($tagText, $wrapLength);
|
||
|
}
|
||
|
|
||
|
$tagText = str_replace(
|
||
|
"\n",
|
||
|
sprintf("\n%s * ", $indent),
|
||
|
$tagText
|
||
|
);
|
||
|
|
||
|
$comment .= sprintf("%s * %s\n", $indent, $tagText);
|
||
|
}
|
||
|
|
||
|
return $comment;
|
||
|
}
|
||
|
}
|