public function check(ReflectionBase $element)
{
$messages = array();
if (empty($element->shortDescription)) {
$annotations = $element->getAnnotations();
if (empty($annotations)) {
$messages[] = new Message(sprintf('Missing documentation of %s', Report::getElementLabel($element)), $element->getStartLine());
} else {
$messages[] = new Message(sprintf('Missing description of %s', Report::getElementLabel($element)), $element->getStartLine());
}
}
return $messages;
}
public function check(ReflectionBase $element)
{
$messages = array();
$annotations = $element->getAnnotations();
if (!isset($annotations['var'])) {
$messages[] = new Message(sprintf('Missing documentation of the data type of %s', Report::getElementLabel($element)), $element->getStartLine());
} elseif (!preg_match('~^[\\w\\\\]+(?:\\[\\])?(?:\\|[\\w\\\\]+(?:\\[\\])?)*(?:\\s+.+)?$~s', $annotations['var'][0])) {
$messages[] = new Message(sprintf('Invalid documentation "%s" of the data type of %s', $annotations['var'][0], Report::getElementLabel($element)), $element->getStartLine(), Message::SEVERITY_WARNING);
}
if (isset($annotations['var'][1])) {
$messages[] = new Message(sprintf('Duplicate documentation "%s" of the data type of %s', $annotations['var'][1], Report::getElementLabel($element)), $element->getStartLine(), Message::SEVERITY_WARNING);
}
return $messages;
}
/**
* Generates list of poorly documented elements.
*
* @return \ApiGen\Generator
*/
private function generateReport()
{
$elements = array();
foreach ($this->getElementTypes() as $type) {
$elements = array_merge($elements, $this->{$type});
}
$report = new Checkstyle\Report($elements);
$report->addCheck(new Checkstyle\DescriptionCheck())->addCheck(new Checkstyle\FunctionCheck())->addCheck(new Checkstyle\DataTypeCheck());
$report->make($this->config->report);
$this->fireEvent('generateProgress', 1);
return $this;
}
public function check(ReflectionBase $element)
{
$messages = array();
$annotations = $element->getAnnotations();
$label = Report::getElementLabel($element);
$line = $element->getStartLine();
// Parameters
$unlimited = false;
foreach ($element->getParameters() as $no => $parameter) {
if (!isset($annotations['param'][$no])) {
$messages[] = new Message(sprintf('Missing documentation of %s', Report::getElementLabel($parameter)), $line);
continue;
}
if (!preg_match('~^[\\w\\\\]+(?:\\[\\])?(?:\\|[\\w\\\\]+(?:\\[\\])?)*(?:\\s+\\$' . $parameter->getName() . ($parameter->isUnlimited() ? ',\\.{3}' : '') . ')?(?:\\s+.+)?$~s', $annotations['param'][$no])) {
$messages[] = new Message(sprintf('Invalid documentation "%s" of %s', $annotations['param'][$no], Report::getElementLabel($parameter)), $line, Message::SEVERITY_WARNING);
}
if ($unlimited && $parameter->isUnlimited()) {
$messages[] = new Message(sprintf('More than one unlimited parameters of %s', Report::getElementLabel($element)), $line, Message::SEVERITY_WARNING);
} elseif ($parameter->isUnlimited()) {
$unlimited = true;
}
unset($annotations['param'][$no]);
}
if (isset($annotations['param'])) {
foreach ($annotations['param'] as $annotation) {
$messages[] = new Message(sprintf('Existing documentation "%s" of nonexistent parameter of %s', $annotation, $label), $line, Message::SEVERITY_WARNING);
}
}
$parentElement = $element instanceof ReflectionMethod ? $element->getDeclaringClass() : $element;
$tokens = $parentElement->getBroker()->getFileTokens($parentElement->getFileName());
// Return values
$return = false;
$tokens->seek($element->getStartPosition())->find(T_FUNCTION);
while ($tokens->next() && $tokens->key() < $element->getEndPosition()) {
$type = $tokens->getType();
if (T_FUNCTION === $type) {
// Skip annonymous functions
$tokens->find('{')->findMatchingBracket();
} elseif (T_RETURN === $type && !$tokens->skipWhitespaces()->is(';')) {
// Skip return without return value
$return = true;
break;
}
}
if ($return && !isset($annotations['return'])) {
$messages[] = new Message(sprintf('Missing documentation of return value of %s', $label), $line);
} elseif (isset($annotations['return'])) {
if (!$return && 'void' !== $annotations['return'][0] && ($element instanceof ReflectionFunction || !$parentElement->isInterface() && !$element->isAbstract())) {
$messages[] = new Message(sprintf('Existing documentation "%s" of nonexistent return value of %s', $annotations['return'][0], $label), $line, Message::SEVERITY_WARNING);
} elseif (!preg_match('~^[\\w\\\\]+(?:\\[\\])?(?:\\|[\\w\\\\]+(?:\\[\\])?)*(?:\\s+.+)?$~s', $annotations['return'][0])) {
$messages[] = new Message(sprintf('Invalid documentation "%s" of return value of %s', $annotations['return'][0], $label), $line, Message::SEVERITY_WARNING);
}
}
if (isset($annotations['return'][1])) {
$messages[] = new Message(sprintf('Duplicate documentation "%s" of return value of %s', $annotations['return'][1], $label), $line, Message::SEVERITY_WARNING);
}
// Throwing exceptions
$throw = false;
$tokens->seek($element->getStartPosition())->find(T_FUNCTION);
while ($tokens->next() && $tokens->key() < $element->getEndPosition()) {
$type = $tokens->getType();
if (T_TRY === $type) {
// Skip try
$tokens->find('{')->findMatchingBracket();
} elseif (T_THROW === $type) {
$throw = true;
break;
}
}
if ($throw && !isset($annotations['throws'])) {
$messages[] = new Message(sprintf('Missing documentation of throwing an exception of %s', $label), $line);
} elseif (isset($annotations['throws']) && !preg_match('~^[\\w\\\\]+(?:\\|[\\w\\\\]+)*(?:\\s+.+)?$~s', $annotations['throws'][0])) {
$messages[] = new Message(sprintf('Invalid documentation "%s" of throwing an exception of %s', $annotations['throws'][0], $label), $line, Message::SEVERITY_WARNING);
}
return $messages;
}
