/**
* Parse a comment to extract the description and the tags
*
* [!!] Converting the output to HTML in this method is deprecated in 3.3
*
* @param string $comment The DocBlock to parse
* @param boolean $html Whether or not to convert the return values
* to HTML (deprecated)
* @return array array(string $description, array $tags)
*/
public static function parse($comment, $html = TRUE)
{
// Normalize all new lines to \n
$comment = str_replace(array("\r\n", "\n"), "\n", $comment);
// Split into lines while capturing without leading whitespace
preg_match_all('/^\\s*\\* ?(.*)\\n/m', $comment, $lines);
// Tag content
$tags = array();
/**
* Process a tag and add it to $tags
*
* @param string $tag Name of the tag without @
* @param string $text Content of the tag
* @return void
*/
$add_tag = function ($tag, $text) use($html, &$tags) {
// Don't show @access lines, they are shown elsewhere
if ($tag !== 'access') {
if ($html) {
$text = Kodoc::format_tag($tag, $text);
}
// Add the tag
$tags[$tag][] = $text;
}
};
$comment = $tag = NULL;
$end = count($lines[1]) - 1;
foreach ($lines[1] as $i => $line) {
// Search this line for a tag
if (preg_match('/^@(\\S+)\\s*(.+)?$/', $line, $matches)) {
if ($tag) {
// Previous tag is finished
$add_tag($tag, $text);
}
$tag = $matches[1];
$text = isset($matches[2]) ? $matches[2] : '';
if ($i === $end) {
// No more lines
$add_tag($tag, $text);
}
} elseif ($tag) {
// This is the continuation of the previous tag
$text .= "\n" . $line;
if ($i === $end) {
// No more lines
$add_tag($tag, $text);
}
} else {
$comment .= "\n" . $line;
}
}
$comment = trim($comment, "\n");
if ($comment and $html) {
// Parse the comment with Markdown
$comment = Kodoc_Markdown::markdown($comment);
}
return array($comment, $tags);
}
/**
* Get the tags of this class as HTML.
*
* @return array
*/
public function tags()
{
$result = array();
foreach ($this->tags as $name => $set) {
foreach ($set as $text) {
$result[$name][] = Kodoc::format_tag($name, $text);
}
}
return $result;
}
