Kodoc_Method
› Kohana_Kodoc_Method
› Kodoc
› Kohana_Kodoc

Class Contents

Class declared in MODPATH/userguide/classes/kodoc/method.php on line 3.

Properties

Methods

public function __construct($class, $method)
{
	$this->method = new ReflectionMethod($class, $method);

	$this->class = $parent = $this->method->getDeclaringClass();

	if ($modifiers = $this->method->getModifiers())
	{
		$this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
	}

	do
	{
		if ($parent->hasMethod($method) AND $comment = $parent->getMethod($method)->getDocComment())
		{
			// Found a description for this method
			break;
		}
	}
	while ($parent = $parent->getParentClass());

	list($this->description, $tags) = Kodoc::parse($comment);

	if ($file = $this->class->getFileName())
	{
		$this->source = Kodoc::source($file, $this->method->getStartLine(), $this->method->getEndLine());
	}

	if (isset($tags['param']))
	{
		$params = array();

		foreach ($this->method->getParameters() as $i => $param)
		{
			$param = new Kodoc_Method_Param(array($this->method->class,$this->method->name),$i);

			if (isset($tags['param'][$i]))
			{
				preg_match('/^(\S+)(?:\s*(?:\$'.$param->name.'\s*)?(.+))?$/', $tags['param'][$i], $matches);

				$param->type = $matches[1];

				if (isset($matches[2]))
				{
					$param->description = $matches[2];
				}
			}
			$params[] = $param;
		}

		$this->params = $params;

		unset($tags['param']);
	}

	if (isset($tags['return']))
	{
		foreach ($tags['return'] as $return)
		{
			if (preg_match('/^(\S*)(?:\s*(.+?))?$/', $return, $matches))
			{
				$this->return[] = array($matches[1], isset($matches[2]) ? $matches[2] : '');
			}
		}

		unset($tags['return']);
	}

	$this->tags = $tags;
}

public function params_short()
{
	$out = '';
	$required = TRUE;
	$first = TRUE;
	foreach ($this->params as $param)
	{
		if ($required AND $param->default AND $first)
		{
			$out .= '[ '.$param;
			$required = FALSE;
			$first = FALSE;
		}
		elseif ($required AND $param->default)
		{
			$out .= '[, '.$param;
			$required = FALSE;
		}
		elseif ($first)
		{
			$out .= $param;
			$first = FALSE;
		}
		else
		{
			$out .= ', '.$param;
		}
	}

	if ( ! $required)
	{
		$out .= '] ';
	}

	return $out;
}

public static function class_methods(array $list = NULL)
{
	$list = Kodoc::classes($list);

	$classes = array();

	foreach ($list as $class)
	{
		$_class = new ReflectionClass($class);

		if (stripos($_class->name, 'Kohana') === 0)
		{
			// Skip the extension stuff stuff
			continue;
		}

		$methods = array();

		foreach ($_class->getMethods() as $_method)
		{
			$declares = $_method->getDeclaringClass()->name;

			if (stripos($declares, 'Kohana') === 0)
			{
				// Remove "Kohana_"
				$declares = substr($declares, 7);
			}

			if ($declares === $_class->name)
			{
				$methods[] = $_method->name;
			}
		}

		sort($methods);

		$classes[$_class->name] = $methods;
	}

	return $classes;
}

public static function classes(array $list = NULL)
{
	if ($list === NULL)
	{
		$list = Kohana::list_files('classes');
	}

	$classes = array();

	foreach ($list as $name => $path)
	{
		if (is_array($path))
		{
			$classes += Kodoc::classes($path);
		}
		else
		{
			// Remove "classes/" and the extension
			$class = substr($name, 8, -(strlen(EXT)));

			// Convert slashes to underscores
			$class = str_replace(DIRECTORY_SEPARATOR, '_', strtolower($class));

			$classes[$class] = $class;
		}
	}

	return $classes;
}

public static function factory($class)
{
	return new Kodoc_Class($class);
}

public static function menu()
{
	$classes = Kodoc::classes();

	foreach ($classes as $class)
	{
		if (isset($classes['kohana_'.$class]))
		{
			// Remove extended classes
			unset($classes['kohana_'.$class]);
		}
	}

	ksort($classes);

	$menu = array();

	$route = Route::get('docs/api');

	foreach ($classes as $class)
	{
		$class = Kodoc_Class::factory($class);

		// Test if we should show this class
		if ( ! Kodoc::show_class($class))
			continue;

		$link = HTML::anchor($route->uri(array('class' => $class->class->name)), $class->class->name);

		if (isset($class->tags['package']))
		{
			foreach ($class->tags['package'] as $package)
			{
				if (isset($class->tags['category']))
				{
					foreach ($class->tags['category'] as $category)
					{
						$menu[$package][$category][] = $link;
					}
				}
				else
				{
					$menu[$package]['Base'][] = $link;
				}
			}
		}
		else
		{
			$menu['[Unknown]']['Base'][] = $link;
		}
	}

	// Sort the packages
	ksort($menu);

	return View::factory('userguide/api/menu')
		->bind('menu', $menu);
}

public static function parse($comment)
{
	// Normalize all new lines to \n
	$comment = str_replace(array("\r\n", "\n"), "\n", $comment);

	// Remove the phpdoc open/close tags and split
	$comment = array_slice(explode("\n", $comment), 1, -1);

	// Tag content
	$tags = array();

	foreach ($comment as $i => $line)
	{
		// Remove all leading whitespace
		$line = preg_replace('/^\s*\* ?/m', '', $line);

		// Search this line for a tag
		if (preg_match('/^@(\S+)(?:\s*(.+))?$/', $line, $matches))
		{
			// This is a tag line
			unset($comment[$i]);

			$name = $matches[1];
			$text = isset($matches[2]) ? $matches[2] : '';

			switch ($name)
			{
				case 'license':
					if (strpos($text, '://') !== FALSE)
					{
						// Convert the lincense into a link
						$text = HTML::anchor($text);
					}
				break;
				case 'link':
					$text = preg_split('/\s+/', $text, 2);
					$text = HTML::anchor($text[0], isset($text[1]) ? $text[1] : $text[0]);
				break;
				case 'copyright':
					if (strpos($text, '(c)') !== FALSE)
					{
						// Convert the copyright sign
						$text = str_replace('(c)', '©', $text);
					}
				break;
				case 'throws':
					if (preg_match('/^(\w+)\W(.*)$/',$text,$matches))
					{
						$text = HTML::anchor(Route::get('docs/api')->uri(array('class' => $matches[1])), $matches[1]).' '.$matches[2];
					}
					else
					{
						$text = HTML::anchor(Route::get('docs/api')->uri(array('class' => $text)), $text);
					}
				break;
				case 'uses':
					if (preg_match('/^([a-z_]+)::([a-z_]+)$/i', $text, $matches))
					{
						// Make a class#method API link
						$text = HTML::anchor(Route::get('docs/api')->uri(array('class' => $matches[1])).'#'.$matches[2], $text);
					}
				break;
				// Don't show @access lines, they are shown elsewhere
				case 'access':
					continue 2;
			}

			// Add the tag
			$tags[$name][] = $text;
		}
		else
		{
			// Overwrite the comment line
			$comment[$i] = (string) $line;
		}
	}

	// Concat the comment lines back to a block of text
	if ($comment = trim(implode("\n", $comment)))
	{
		// Parse the comment with Markdown
		$comment = Markdown($comment);
	}

	return array($comment, $tags);
}

public static function show_class(Kodoc_Class $class)
{
	$api_packages = Kohana::config('userguide.api_packages');

	// If api_packages is true, all packages should be shown
	if ($api_packages === TRUE)
		return TRUE;

	// Get the package tags for this class (as an array)
	$packages = Arr::get($class->tags,'package',Array('None'));

	$show_this = FALSE;

	// Loop through each package tag
	foreach ($packages as $package)
	{
		// If this package is in the allowed packages, set show this to true
		if (in_array($package,explode(',',$api_packages)))
			$show_this = TRUE;
	}

	return $show_this;
}

public static function source($file, $start, $end)
{
	if ( ! $file)
	{
		return FALSE;
	}

	$file = file($file, FILE_IGNORE_NEW_LINES);

	$file = array_slice($file, $start - 1, $end - $start + 1);

	if (preg_match('/^(\s+)/', $file[0], $matches))
	{
		$padding = strlen($matches[1]);

		foreach ($file as & $line)
		{
			$line = substr($line, $padding);
		}
	}

	return implode("\n", $file);
}