Returns the full description or also known as long description.
|
public getLongDescription ( ) : |
||
| return | ||
protected function addLongDescription(\DOMElement $child, \phpDocumentor\Reflection\DocBlock $docblock)
{
$node = $child->ownerDocument->createCDATASection($docblock->getLongDescription()->getFormattedContents());
$element = new \DOMElement('long-description');
$child->appendChild($element);
$element->appendChild($node);
}
protected function configure()
{
$reflection = new \ReflectionClass(get_called_class());
$baseNamespaceChunks = [];
foreach (explode('\\', $reflection->getNamespaceName()) as $namespaceChunk) {
$baseNamespaceChunks[] = $namespaceChunk;
if ($namespaceChunk == consoleBase::COMMANDS_DIRECTORY) {
break;
}
}
$namespace = str_replace(implode('\\', $baseNamespaceChunks), '', get_called_class());
$namespace = trim($namespace, '\\');
$commandNameData = explode('\\', $namespace);
$phpdoc = new DocBlock($reflection);
/** @var DocBlock\Tag $tag */
$tag = reset($phpdoc->getTagsByName('consoleNs'));
$commandNameValues = [];
if ($tag) {
$consoleNs = trim($tag->getDescription());
if (!empty($consoleNs)) {
$commandNameValues[] = $consoleNs;
}
}
foreach ($commandNameData as $commandNameValue) {
$commandNameValues[] = $commandNameValue;
}
$this->setName(implode(':', $commandNameValues))->setDescription($phpdoc->getShortDescription())->setHelp($phpdoc->getLongDescription());
$this->defineArguments();
}
/**
* Parse the docBlock comment for this command, and set the
* fields of this class with the data thereby obtained.
*/
public function parse()
{
$docblockComment = $this->reflection->getDocComment();
$phpdoc = new DocBlock($docblockComment);
// First set the description (synopsis) and help.
$this->commandInfo->setDescription((string) $phpdoc->getShortDescription());
$this->commandInfo->setHelp((string) $phpdoc->getLongDescription());
$this->processAllTags($phpdoc);
}
public function getMethodsDetails()
{
$methods = [];
foreach ($this->reflection->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
$docblock = new DocBlock($method);
$data = ['shortDescription' => $docblock->getShortDescription(), 'longDescription' => $docblock->getLongDescription(), 'argumentsList' => $this->retriveParams($docblock->getTagsByName('param')), 'argumentsDescription' => $this->retriveParamsDescription($docblock->getTagsByName('param')), 'returnValue' => $this->retriveReturnValue($docblock->getTagsByName('return')), 'visibility' => join('', [$method->isFinal() ? 'final ' : '', 'public', $method->isStatic() ? ' static' : ''])];
if (strlen($data['shortDescription'])) {
$methods[$method->getName()] = (object) $data;
}
}
return $methods;
}
public function getMethodDesc($methodName)
{
if (!$this->reflection->hasMethod($methodName)) {
return null;
}
$docComment = $this->reflection->getMethod($methodName)->getDocComment();
if ($docComment) {
$docBlock = new DocBlock($docComment);
return join(' ', [$docBlock->getShortDescription(), $docBlock->getLongDescription()]);
}
return null;
}
/**
* @param $doc
* @return bool
*/
public function parseClass(ControllerDoc $doc)
{
if (!($docBlock = new DocBlock($this->reflection))) {
return false;
}
$doc->longDescription = $docBlock->getLongDescription()->getContents();
$doc->shortDescription = $docBlock->getShortDescription();
$doc->populateTags($docBlock);
if (DocBlockHelper::isInherit($docBlock)) {
$parentParser = $this->getParentParser();
$parentParser->parseClass($doc);
}
}
/**
* Assemble DocBlock.
*
* @param DocBlock|null $docBlock
* @param DescriptorAbstract $target
*
* @return void
*/
protected function assembleDocBlock($docBlock, $target)
{
if (!$docBlock) {
return;
}
$target->setSummary($docBlock->getShortDescription());
$target->setDescription($docBlock->getLongDescription()->getContents());
/** @var DocBlock\Tag $tag */
foreach ($docBlock->getTags() as $tag) {
$tagDescriptor = $this->builder->buildDescriptor($tag);
// allow filtering of tags
if (!$tagDescriptor) {
continue;
}
$target->getTags()->get($tag->getName(), new Collection())->add($tagDescriptor);
}
}
public function parse($comment, ParserContext $context)
{
$docBlock = null;
$errorMessage = '';
try {
$docBlockContext = new DocBlock\Context($context->getNamespace(), $context->getAliases() ?: array());
$docBlock = new DocBlock((string) $comment, $docBlockContext);
} catch (\Exception $e) {
$errorMessage = $e->getMessage();
}
$result = new DocBlockNode();
if ($errorMessage) {
$result->addError($errorMessage);
return $result;
}
$result->setShortDesc($docBlock->getShortDescription());
$result->setLongDesc((string) $docBlock->getLongDescription());
foreach ($docBlock->getTags() as $tag) {
$result->addTag($tag->getName(), $this->parseTag($tag));
}
return $result;
}
function __construct($reflector)
{
$phpdoc = new \phpDocumentor\Reflection\DocBlock($reflector);
$this->tags = array();
$this->docblock = $reflector->getDocComment();
$this->desc = new stdClass();
$this->desc->long = $phpdoc->getLongDescription()->getFormattedContents();
$this->desc->short = $phpdoc->getShortDescription();
$this->desc->full = strip_tags($this->desc->short . "\n" . $this->desc->long);
foreach ($phpdoc->getTags() as $tag) {
$rslt = self::get_tag();
switch (true) {
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\AuthorName:
$rslt->name = $tag->getAuthorName();
$rslt->email = $tag->getAuthorEmail();
break;
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\SeeTag:
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\UsesTag:
$rslt->ref = $tag->getReference();
break;
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\ExampleTag:
$rslt->file_path = $tag->getFilePath();
break;
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\LinkTag:
$rslt->link = $tag->getLink();
break;
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\MethodTag:
$rslt->name = $tag->getMethodName();
$rslt->args = $tag->getArguments();
break;
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\VarTag:
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\ParamTag:
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\PropertyTag:
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\PropertyReadTag:
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\PropertyWriteTag:
$rslt->name = $tag->getVariableName();
$rslt->type = str_replace('\\', '', $tag->getType());
break;
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\ReturnTag:
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\ThrowsTag:
$rslt->type = str_replace('\\', '', $tag->getType());
break;
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\SinceTag:
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\VersionTag:
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\DeprecatedTag:
$rslt->version = $tag->getVersion();
break;
case $tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\SourceTag:
$rslt->line = new stdClass();
$rslt->line->count = $tag->getLineCount();
$rslt->line->starting = $tag->getStartingLine();
break;
default:
break;
}
$rslt->desc = $tag->getDescription();
$name = $tag->getName();
if (@isset($rslt->name)) {
$rslt->name = rtrim($rslt->name, ':');
}
if ($tag instanceof \phpDocumentor\Reflection\DocBlock\Tag\ParamTag) {
if (!@isset($this->tags[$name])) {
$this->tags[$name] = array();
}
$this->tags[$name][] = $rslt;
} else {
$this->tags[$name] = $rslt;
}
}
}
/**
* @param DocBlock $docBlock
* @param \SimpleXMLElement $xmlElement
*/
protected function setDescriptions($docBlock, $xmlElement)
{
if ($docBlock->getShortDescription()) {
$shortDesc = $xmlElement->addChild('shortdesc', $docBlock->getShortDescription());
$shortDesc->addAttribute('lang', $this->language);
}
if ($docBlock->getLongDescription()->getContents()) {
$longDesc = $xmlElement->addChild('longdesc', $docBlock->getLongDescription()->getContents());
$longDesc->addAttribute('lang', $this->language);
}
}
/**
* Process an individual file
*
* @param string $file File path
* @return array Processed endpoints
*/
private function processFile($file)
{
// var to hold output
$output = array();
require_once $file;
$className = $this->parseClassFromFile($file);
$component = $this->parseClassFromFile($file, true)['component'];
$version = $this->parseClassFromFile($file, true)['version'];
// Push file to files array
$this->output['files'][] = $file;
// Push version to versions array
$this->output['versions']['available'][] = $version;
if (!class_exists($className)) {
return $output;
}
$classReflector = new ReflectionClass($className);
foreach ($classReflector->getMethods() as $method) {
// Create docblock object & make sure we have something
$phpdoc = new DocBlock($method);
// Skip methods we don't want processed
if (substr($method->getName(), -4) != 'Task' || in_array($method->getName(), array('registerTask', 'unregisterTask', 'indexTask'))) {
continue;
}
// Skip method in the parent class (already processed),
if ($className != $method->getDeclaringClass()->getName()) {
//continue;
}
// Skip if we dont have a short desc
// but put in error
if (!$phpdoc->getShortDescription()) {
$this->output['errors'][] = sprintf('Missing docblock for method "%s" in "%s"', $method->getName(), $file);
continue;
}
// Create endpoint data array
$endpoint = array('name' => $phpdoc->getShortDescription(), 'description' => $phpdoc->getLongDescription()->getContents(), 'method' => '', 'uri' => '', 'parameters' => array(), '_metadata' => array('component' => $component, 'version' => $version, 'method' => $method->getName()));
// Loop through each tag
foreach ($phpdoc->getTags() as $tag) {
$name = strtolower(str_replace('api', '', $tag->getName()));
$content = $tag->getContent();
// Handle parameters separately
// json decode param input
if ($name == 'parameter') {
$parameter = json_decode($content);
if (json_last_error() != JSON_ERROR_NONE) {
$this->output['errors'][] = sprintf('Unable to parse parameter info for method "%s" in "%s"', $method->getName(), $file);
continue;
}
$endpoint['parameters'][] = (array) $parameter;
continue;
}
if ($name == 'uri' && $method->getName() == 'indexTask') {
$content .= $component;
}
// Add data to endpoint data
$endpoint[$name] = $content;
}
// Add endpoint to output
// We always want indexTask to be first in the list
if ($method->getName() == 'indexTask') {
array_unshift($output, $endpoint);
} else {
$output[] = $endpoint;
}
}
return $output;
}
public function testTagCaseSensitivity()
{
$fixture = <<<DOCBLOCK
/**
* This is a short description.
*
* This is a long description.
*
* @method null something()
* @Method({"GET", "POST"})
*/
DOCBLOCK;
$object = new DocBlock($fixture);
$this->assertEquals('This is a short description.', $object->getShortDescription());
$this->assertEquals('This is a long description.', $object->getLongDescription()->getContents());
$tags = $object->getTags();
$this->assertCount(2, $tags);
$this->assertTrue($object->hasTag('method'));
$this->assertTrue($object->hasTag('Method'));
$this->assertInstanceOf(__NAMESPACE__ . '\\DocBlock\\Tag\\MethodTag', $tags[0]);
$this->assertInstanceOf(__NAMESPACE__ . '\\DocBlock\\Tag', $tags[1]);
$this->assertNotInstanceOf(__NAMESPACE__ . '\\DocBlock\\Tag\\MethodTag', $tags[1]);
}
/**
* Парсит описание метода из phpdoc в стандартизованный вид для дальнейшей обработки
* @param string $text
* @return string
*/
protected function parseMdMethodFromPHPDoc($text)
{
$lines = $this->getTextLines($text);
$link = '';
$code = trim(array_pop($lines));
if (strpos($code, 'link:') === 0) {
$link = substr($code, 5);
$code = trim(array_pop($lines));
}
$code_out_params = trim(substr($code, 0, strpos($code, '(')));
$comment = implode("\n", $lines);
$args = [];
preg_match_all('/(\\$[a-zA-Z_\\x7f-\\xff][a-zA-Z0-9_\\x7f-\\xff]*)\\s*\\=\\s*(.+?)(\\,|\\))/', $code, $matches, PREG_SET_ORDER);
foreach ($matches as $matche) {
$args[$matche[1]] = $matche[2];
}
$code_params = [];
$desc_params = [];
$PHPDoc = new DocBlock($comment);
$doc_result = $PHPDoc->getTagsByName('return');
$code_return_type = empty($doc_result) ? 'void' : $this->getDocDefaultType($doc_result[0]->getType());
$doc_params = $PHPDoc->getTagsByName('param');
$doc_callbacks = $PHPDoc->getTagsByName('callback');
$callbacks = [];
foreach ($doc_callbacks as $cb) {
list($cb_name, $cb_code) = explode(' ', $cb->getDescription(), 2);
$callbacks[$cb_name] = $cb_code;
}
foreach ($doc_params as $tag) {
$name = $tag->getVariableName();
$type = $tag->getType();
$desc = $tag->getDescription();
$deftype = $this->getDocDefaultType($type);
if ($name === '' && $desc !== '' && $desc[0] === '&' && $desc[1] === '$') {
if (strpos($desc, ' ') === false) {
$name = $desc;
$desc = '';
} else {
list($name, $desc) = explode(' ', $desc, 2);
}
}
$code_params[] = $deftype . ' ' . $name . (isset($args[$name]) ? ' = ' . $args[$name] : '');
$extra = '';
if ($deftype === 'callable') {
if (isset($callbacks[$name])) {
$extra = "callback {$callbacks[$name]}\n";
}
}
$desc_params[] = $name . "\n" . $extra . $desc;
}
$result = '';
if ($link) {
$result .= 'link:' . $link . "\n";
}
// $desc_text_arr = preg_split('/[ \t]*\n[ \t]*/', trim($PHPDoc->getShortDescription() ."\n". $PHPDoc->getLongDescription()), -1, PREG_SPLIT_NO_EMPTY);
// $desc_text = ' ' . implode(" \n ", $desc_text_arr);
$desc_text = $this->convertTextToHTML(trim($PHPDoc->getShortDescription() . "\n\n" . $PHPDoc->getLongDescription()));
$doc_methods = $PHPDoc->getTagsByName('call');
if (empty($doc_methods)) {
$result .= $this->showReturnType($code_return_type) . ' ' . $code_out_params . ' ( ' . implode(', ', $code_params) . " )\n\n";
} else {
foreach ($doc_methods as $tag) {
$result .= $tag->getDescription() . "<i class='dn'>;</i>\n";
}
$result .= "\n";
}
$result .= $desc_text . "\n\n";
$result .= implode("\n\n", $desc_params);
return $result;
}
private function getMethodDetails($method)
{
$docblock = new DocBlock($method);
$data = ['shortDescription' => $docblock->getShortDescription(), 'longDescription' => $docblock->getLongDescription(), 'argumentsList' => $this->retriveParams($docblock->getTagsByName('param')), 'argumentsDescription' => $this->retriveParamsDescription($docblock->getTagsByName('param')), 'returnValue' => $this->retriveReturnValue($docblock->getTagsByName('return')), 'visibility' => join('', [$method->isFinal() ? 'final ' : '', 'public', $method->isStatic() ? ' static' : ''])];
return (object) $data;
}
/**
* Adds the DocBlock's long description to the $child element,
*
* @param \DOMElement $child
* @param DocBlock $docblock
*
* @return void
*/
protected function addLongDescription(\DOMElement $child, \phpDocumentor\Reflection\DocBlock $docblock)
{
$child->appendChild(new \DOMElement('long-description'))->appendChild(new \DOMText($docblock->getLongDescription()->getFormattedContents()));
}
