/**
* If the ProjectDescriptor's settings allow internal tags then return the Descriptor, otherwise null to filter it.
*
* @param DescriptorAbstract $value
*
* @return DescriptorAbstract|null
*/
public function filter($value)
{
$isInternalAllowed = $this->builder->isVisibilityAllowed(Settings::VISIBILITY_INTERNAL);
if ($isInternalAllowed) {
$value->setDescription(preg_replace('/{@internal\\ (.+)}}/', '$1', $value->getDescription()));
return $value;
}
// remove inline @internal tags
$value->setDescription(preg_replace('/{@internal\\ .+}}/', '', $value->getDescription()));
// if internal elements are not allowed; filter this element
if ($value->getTags()->get('internal')) {
return null;
}
return $value;
}
/**
* Replaces the example tags in the description with the contents of the found example.
*
* @param DescriptorAbstract $element
*
* @return string
*/
protected function replaceInlineExamples(DescriptorAbstract $element)
{
$description = $element->getDescription();
$matches = array();
if (!$description || !preg_match_all('/\\{@example\\s(.+?)\\}/', $description, $matches) || count($matches[0]) < 1) {
return $description;
}
$matched = array();
foreach ($matches[0] as $index => $match) {
if (isset($matched[$match])) {
continue;
}
$matched[$match] = true;
$exampleReflector = new ExampleTag('example', $matches[1][$index]);
$example = $this->exampleAssembler->create($exampleReflector);
$replacement = '`' . $example->getExample() . '`';
if ($example->getDescription()) {
$replacement = '*' . $example->getDescription() . '*' . $replacement;
}
$description = str_replace($match, $replacement, $description);
}
return $description;
}
/**
* @covers phpDocumentor\Descriptor\DescriptorAbstract::setDescription
* @covers phpDocumentor\Descriptor\DescriptorAbstract::getDescription
*/
public function testSettingAndGettingDescription()
{
$this->assertSame('', $this->fixture->getDescription());
$this->fixture->setDescription('description');
$this->assertSame('description', $this->fixture->getDescription());
}
/**
* Resolves all @see and @link tags in the description of the given descriptor to their markdown representation.
*
* @param DescriptorAbstract $descriptor
*
* @uses self::resolveTag()
*
* @return void
*/
private function resolveSeeAndLinkTags(DescriptorAbstract $descriptor)
{
// store descriptor to use it in the resolveTag method
$this->descriptor = $descriptor;
$descriptor->setDescription(preg_replace_callback(self::REGEX_INLINE_LINK_OR_SEE_TAG, array($this, 'resolveTag'), $descriptor->getDescription()));
}
/**
* Adds the DocBlock's long description to the $child element,
*
* @param \DOMElement $node
* @param DescriptorAbstract $element
*
* @return void
*/
protected function addDescription(\DOMElement $node, DescriptorAbstract $element)
{
$node->appendChild(new \DOMElement('long-description'))->appendChild(new \DOMText($element->getDescription()));
}