Upgrade to KH 3.3.0

includes/kohana/modules/userguide/classes/Controller/Userguide.php

@@ -0,0 +1,3 @@
+<?php defined('SYSPATH') OR die('No direct script access.');
+
+class Controller_Userguide extends Kohana_Controller_Userguide {}

includes/kohana/modules/userguide/classes/Kohana/Controller/Userguide.php

@@ -6,7 +6,7 @@
  * @category   Controllers
  * @author     Kohana Team
  */
-class Controller_Userguide extends Controller_Template {
+abstract class Kohana_Controller_Userguide extends Controller_Template {
 
 	public $template = 'userguide/template';
 
@@ -17,6 +17,8 @@ class Controller_Userguide extends Controller_Template {
 
 	public function before()
 	{
+		parent::before();
+
 		if ($this->request->action() === 'media')
 		{
 			// Do not template media files
@@ -28,28 +30,15 @@ class Controller_Userguide extends Controller_Template {
 			$this->media = Route::get('docs/media');
 			$this->guide = Route::get('docs/guide');
 
-			if (defined('MARKDOWN_PARSER_CLASS'))
-			{
-				throw new Kohana_Exception('Markdown parser already registered. Live documentation will not work in your environment.');
-			}
-
-			// Use customized Markdown parser
-			define('MARKDOWN_PARSER_CLASS', 'Kodoc_Markdown');
-
-			if ( ! class_exists('Markdown', FALSE))
-			{
-				// Load Markdown support
-				require Kohana::find_file('vendor', 'markdown/markdown');
-			}
-
 			// Set the base URL for links and images
 			Kodoc_Markdown::$base_url  = URL::site($this->guide->uri()).'/';
 			Kodoc_Markdown::$image_url = URL::site($this->media->uri()).'/';
 		}
 
-		parent::before();
+		// Default show_comments to config value
+		$this->template->show_comments = Kohana::$config->load('userguide.show_comments');
 	}
-
+	
 	// List all modules that have userguides
 	public function index()
 	{
@@ -57,32 +46,32 @@ class Controller_Userguide extends Controller_Template {
 		$this->template->breadcrumb = array('User Guide');
 		$this->template->content = View::factory('userguide/index', array('modules' => $this->_modules()));
 		$this->template->menu = View::factory('userguide/menu', array('modules' => $this->_modules()));
-
+		
 		// Don't show disqus on the index page
-		$this->template->hide_disqus = TRUE;
+		$this->template->show_comments = FALSE;
 	}
-
+	
 	// Display an error if a page isn't found
 	public function error($message)
 	{
 		$this->response->status(404);
 		$this->template->title = "Userguide - Error";
 		$this->template->content = View::factory('userguide/error',array('message' => $message));
-
+		
 		// Don't show disqus on error pages
-		$this->template->hide_disqus = TRUE;
+		$this->template->show_comments = FALSE;
 
 		// If we are in a module and that module has a menu, show that
-		if ($module = $this->request->param('module') AND $menu = $this->file($module.'/menu') AND Kohana::config('userguide.modules.'.$module.'.enabled'))
+		if ($module = $this->request->param('module') AND $menu = $this->file($module.'/menu') AND Kohana::$config->load('userguide.modules.'.$module.'.enabled'))
 		{
 			// Namespace the markdown parser
 			Kodoc_Markdown::$base_url  = URL::site($this->guide->uri()).'/'.$module.'/';
 			Kodoc_Markdown::$image_url = URL::site($this->media->uri()).'/'.$module.'/';
 
-			$this->template->menu = Markdown($this->_get_all_menu_markdown());
+			$this->template->menu = Kodoc_Markdown::markdown($this->_get_all_menu_markdown());
 			$this->template->breadcrumb = array(
 				$this->guide->uri() => 'User Guide',
-				$this->guide->uri(array('module' => $module)) => Kohana::config('userguide.modules.'.$module.'.name'),
+				$this->guide->uri(array('module' => $module)) => Kohana::$config->load('userguide.modules.'.$module.'.name'),
 				'Error'
 			);
 		}
@@ -119,19 +108,19 @@ class Controller_Userguide extends Controller_Template {
 		{
 			return $this->index();
 		}
-
+		
 		// If this module's userguide pages are disabled, show the error page
-		if ( ! Kohana::config('userguide.modules.'.$module.'.enabled'))
+		if ( ! Kohana::$config->load('userguide.modules.'.$module.'.enabled'))
 		{
-			return $this->error(__('That module doesn\'t exist, or has userguide pages disabled.'));
+			return $this->error('That module doesn\'t exist, or has userguide pages disabled.');
 		}
-
+		
 		// Prevent "guide/module" and "guide/module/index" from having duplicate content
 		if ( $page == 'index')
 		{
-			return $this->error(__('Userguide page not found'));
+			return $this->error('Userguide page not found');
 		}
-
+		
 		// If a module is set, but no page was provided in the url, show the index page
 		if ( ! $page )
 		{
@@ -144,37 +133,37 @@ class Controller_Userguide extends Controller_Template {
 		// If it's not found, show the error page
 		if ( ! $file)
 		{
-			return $this->error(__('Userguide page not found'));
+			return $this->error('Userguide page not found');
 		}
-
+		
 		// Namespace the markdown parser
 		Kodoc_Markdown::$base_url  = URL::site($this->guide->uri()).'/'.$module.'/';
 		Kodoc_Markdown::$image_url = URL::site($this->media->uri()).'/'.$module.'/';
 
 		// Set the page title
-		$this->template->title = $page == 'index' ? Kohana::config('userguide.modules.'.$module.'.name') : $this->title($page);
+		$this->template->title = $page == 'index' ? Kohana::$config->load('userguide.modules.'.$module.'.name') : $this->title($page);
 
 		// Parse the page contents into the template
 		Kodoc_Markdown::$show_toc = true;
-		$this->template->content = Markdown(file_get_contents($file));
+		$this->template->content = Kodoc_Markdown::markdown(file_get_contents($file));
 		Kodoc_Markdown::$show_toc = false;
 
 		// Attach this module's menu to the template
-		$this->template->menu = Markdown($this->_get_all_menu_markdown());
+		$this->template->menu = Kodoc_Markdown::markdown($this->_get_all_menu_markdown());
 
 		// Bind the breadcrumb
 		$this->template->bind('breadcrumb', $breadcrumb);
-
+		
 		// Bind the copyright
-		$this->template->copyright = Kohana::config('userguide.modules.'.$module.'.copyright');
+		$this->template->copyright = Kohana::$config->load('userguide.modules.'.$module.'.copyright');
 
 		// Add the breadcrumb trail
 		$breadcrumb = array();
-		$breadcrumb[$this->guide->uri()] = __('User Guide');
-		$breadcrumb[$this->guide->uri(array('module' => $module))] = Kohana::config('userguide.modules.'.$module.'.name');
-
+		$breadcrumb[$this->guide->uri()] = 'User Guide';
+		$breadcrumb[$this->guide->uri(array('module' => $module))] = Kohana::$config->load('userguide.modules.'.$module.'.name');
+		
 		// TODO try and get parent category names (from menu).  Regex magic or javascript dom stuff perhaps?
-
+		
 		// Only add the current page title to breadcrumbs if it isn't the index, otherwise we get repeats.
 		if ($page != 'index')
 		{
@@ -194,7 +183,7 @@ class Controller_Userguide extends Controller_Template {
 		// If no class was passed to the url, display the API index page
 		if ( ! $class)
 		{
-			$this->template->title = __('Table of Contents');
+			$this->template->title = 'Table of Contents';
 
 			$this->template->content = View::factory('userguide/api/toc')
 				->set('classes', Kodoc::class_methods())
@@ -204,7 +193,7 @@ class Controller_Userguide extends Controller_Template {
 		{
 			// Create the Kodoc_Class version of this class.
 			$_class = Kodoc_Class::factory($class);
-
+			
 			// If the class requested and the actual class name are different
 			// (different case, orm vs ORM, auth vs Auth) redirect
 			if ($_class->class->name != $class)
@@ -219,12 +208,12 @@ class Controller_Userguide extends Controller_Template {
 			// If this classes package has been disabled via the config, 404
 			if ( ! Kodoc::show_class($_class))
 				return $this->error('That class is in package that is hidden.  Check the <code>api_packages</code> config setting.');
-
+		
 			// Everything is fine, display the class.
 			$this->template->title = $class;
 
 			$this->template->content = View::factory('userguide/api/class')
-				->set('doc', Kodoc::factory($class))
+				->set('doc', $_class)
 				->set('route', $this->request->route());
 		}
 
@@ -234,12 +223,9 @@ class Controller_Userguide extends Controller_Template {
 		// Bind the breadcrumb
 		$this->template->bind('breadcrumb', $breadcrumb);
 
-		// Get the docs URI
-		$guide = Route::get('docs/guide');
-
 		// Add the breadcrumb
 		$breadcrumb = array();
-		$breadcrumb[$this->guide->uri(array('page' => NULL))] = __('User Guide');
+		$breadcrumb[$this->guide->uri(array('page' => NULL))] = 'User Guide';
 		$breadcrumb[$this->request->route()->uri()] = 'API Browser';
 		$breadcrumb[] = $this->template->title;
 	}
@@ -258,8 +244,8 @@ class Controller_Userguide extends Controller_Template {
 		if ($file = Kohana::find_file('media/guide', $file, $ext))
 		{
 			// Check if the browser sent an "if-none-match: <etag>" header, and tell if the file hasn't changed
-			$this->response->check_cache(sha1($this->request->uri()).filemtime($file), $this->request);
-
+			$this->check_cache(sha1($this->request->uri()).filemtime($file));
+			
 			// Send the file content as the response
 			$this->response->body(file_get_contents($file));
 
@@ -307,83 +293,105 @@ class Controller_Userguide extends Controller_Template {
 		return parent::after();
 	}
 
+	/**
+	 * Locates the appropriate markdown file for a given guide page. Page URLS
+	 * can be specified in one of three forms:
+	 *
+	 *  * userguide/adding
+	 *  * userguide/adding.md
+	 *  * userguide/adding.markdown
+	 *
+	 * In every case, the userguide will search the cascading file system paths
+	 * for the file guide/userguide/adding.md.
+	 *
+	 * @param string $page The relative URL of the guide page
+	 * @return string
+	 */
 	public function file($page)
 	{
+
+		// Strip optional .md or .markdown suffix from the passed filename
+		$info = pathinfo($page);
+		if (isset($info['extension'])
+			AND (($info['extension'] === 'md') OR ($info['extension'] === 'markdown')))
+		{
+			$page = $info['dirname'].DIRECTORY_SEPARATOR.$info['filename'];
+		}
 		return Kohana::find_file('guide', $page, 'md');
 	}
 
 	public function section($page)
 	{
 		$markdown = $this->_get_all_menu_markdown();
-
+		
 		if (preg_match('~\*{2}(.+?)\*{2}[^*]+\[[^\]]+\]\('.preg_quote($page).'\)~mu', $markdown, $matches))
 		{
 			return $matches[1];
 		}
-
+		
 		return $page;
 	}
 
 	public function title($page)
 	{
 		$markdown = $this->_get_all_menu_markdown();
-
+		
 		if (preg_match('~\[([^\]]+)\]\('.preg_quote($page).'\)~mu', $markdown, $matches))
 		{
 			// Found a title for this link
 			return $matches[1];
 		}
-
+		
 		return $page;
 	}
-
+	
 	protected function _get_all_menu_markdown()
 	{
 		// Only do this once per request...
 		static $markdown = '';
-
+		
 		if (empty($markdown))
 		{
 			// Get menu items
 			$file = $this->file($this->request->param('module').'/menu');
-
+	
 			if ($file AND $text = file_get_contents($file))
 			{
 				// Add spans around non-link categories. This is a terrible hack.
-				//echo Kohana::debug($text);
-
+				//echo Debug::vars($text);
+				
 				//$text = preg_replace('/(\s*[\-\*\+]\s*)(.*)/','$1<span>$2</span>',$text);
 				$text = preg_replace('/^(\s*[\-\*\+]\s*)([^\[\]]+)$/m','$1<span>$2</span>',$text);
-				//echo Kohana::debug($text);
+				//echo Debug::vars($text);
 				$markdown .= $text;
 			}
-
+			
 		}
-
+		
 		return $markdown;
 	}
-
+	
 	// Get the list of modules from the config, and reverses it so it displays in the order the modules are added, but move Kohana to the top.
 	protected function _modules()
 	{
-		$modules = array_reverse(Kohana::config('userguide.modules'));
-
+		$modules = array_reverse(Kohana::$config->load('userguide.modules'));
+		
 		if (isset($modules['kohana']))
 		{
 			$kohana = $modules['kohana'];
 			unset($modules['kohana']);
 			$modules = array_merge(array('kohana' => $kohana), $modules);
 		}
-
+		
 		// Remove modules that have been disabled via config
 		foreach ($modules as $key => $value)
 		{
-			if ( ! Kohana::config('userguide.modules.'.$key.'.enabled'))
+			if ( ! Kohana::$config->load('userguide.modules.'.$key.'.enabled'))
 			{
 				unset($modules[$key]);
 			}
 		}
-
+		
 		return $modules;
 	}
 

includes/kohana/modules/userguide/classes/Kohana/Kodoc.php

@@ -5,7 +5,7 @@
  * @package    Kohana/Userguide
  * @category   Base
  * @author     Kohana Team
- * @copyright  (c) 2008-2009 Kohana Team
+ * @copyright  (c) 2008-2012 Kohana Team
  * @license    http://kohanaphp.com/license
  */
 class Kohana_Kodoc {
@@ -57,15 +57,6 @@ class Kohana_Kodoc {
 	{
 		$classes = Kodoc::classes();
 
-		foreach ($classes as $class)
-		{
-			if (isset($classes['kohana_'.$class]))
-			{
-				// Remove extended classes
-				unset($classes['kohana_'.$class]);
-			}
-		}
-
 		ksort($classes);
 
 		$menu = array();
@@ -74,6 +65,9 @@ class Kohana_Kodoc {
 
 		foreach ($classes as $class)
 		{
+			if (Kodoc::is_transparent($class, $classes))
+				continue;
+
 			$class = Kodoc_Class::factory($class);
 
 			// Test if we should show this class
@@ -113,9 +107,7 @@ class Kohana_Kodoc {
 	}
 
 	/**
-	 * Returns an array of all the classes available, built by listing all files in the classes folder and then trying to create that class.
-	 *
-	 * This means any empty class files (as in complety empty) will cause an exception
+	 * Returns an array of all the classes available, built by listing all files in the classes folder.
 	 *
 	 * @param   array   array of files, obtained using Kohana::list_files
 	 * @return  array   an array of all the class names
@@ -129,19 +121,22 @@ class Kohana_Kodoc {
 
 		$classes = array();
 
+		// This will be used a lot!
+		$ext_length = strlen(EXT);
+
 		foreach ($list as $name => $path)
 		{
 			if (is_array($path))
 			{
 				$classes += Kodoc::classes($path);
 			}
-			else
+			elseif (substr($name, -$ext_length) === EXT)
 			{
 				// Remove "classes/" and the extension
-				$class = substr($name, 8, -(strlen(EXT)));
+				$class = substr($name, 8, -$ext_length);
 
 				// Convert slashes to underscores
-				$class = str_replace(DIRECTORY_SEPARATOR, '_', strtolower($class));
+				$class = str_replace(DIRECTORY_SEPARATOR, '_', $class);
 
 				$classes[$class] = $class;
 			}
@@ -166,13 +161,11 @@ class Kohana_Kodoc {
 
 		foreach ($list as $class)
 		{
-			$_class = new ReflectionClass($class);
-
-			if (stripos($_class->name, 'Kohana_') === 0)
-			{
-				// Skip transparent extension classes
+			// Skip transparent extension classes
+			if (Kodoc::is_transparent($class))
 				continue;
-			}
+
+			$_class = new ReflectionClass($class);
 
 			$methods = array();
 
@@ -180,10 +173,10 @@ class Kohana_Kodoc {
 			{
 				$declares = $_method->getDeclaringClass()->name;
 
-				if (stripos($declares, 'Kohana_') === 0)
+				// Remove the transparent prefix from declaring classes
+				if ($child = Kodoc::is_transparent($declares))
 				{
-					// Remove "Kohana_"
-					$declares = substr($declares, 7);
+					$declares = $child;
 				}
 
 				if ($declares === $_class->name OR $declares === "Core")
@@ -200,93 +193,149 @@ class Kohana_Kodoc {
 		return $classes;
 	}
 
+	/**
+	 * Generate HTML for the content of a tag.
+	 *
+	 * @param   string  $tag    Name of the tag without @
+	 * @param   string  $text   Content of the tag
+	 * @return  string  HTML
+	 */
+	public static function format_tag($tag, $text)
+	{
+		if ($tag === 'license')
+		{
+			if (strpos($text, '://') !== FALSE)
+				return HTML::anchor($text);
+		}
+		elseif ($tag === 'link')
+		{
+			$split = preg_split('/\s+/', $text, 2);
+
+			return HTML::anchor(
+				$split[0],
+				isset($split[1]) ? $split[1] : $split[0]
+			);
+		}
+		elseif ($tag === 'copyright')
+		{
+			// Convert the copyright symbol
+			return str_replace('(c)', '©', $text);
+		}
+		elseif ($tag === 'throws')
+		{
+			$route = Route::get('docs/api');
+
+			if (preg_match('/^(\w+)\W(.*)$/D', $text, $matches))
+			{
+				return HTML::anchor(
+					$route->uri(array('class' => $matches[1])),
+					$matches[1]
+				).' '.$matches[2];
+			}
+
+			return HTML::anchor(
+				$route->uri(array('class' => $text)),
+				$text
+			);
+		}
+		elseif ($tag === 'see' OR $tag === 'uses')
+		{
+			if (preg_match('/^'.Kodoc::$regex_class_member.'/', $text, $matches))
+				return Kodoc::link_class_member($matches);
+		}
+
+		return $text;
+	}
+
 	/**
 	 * Parse a comment to extract the description and the tags
 	 *
-	 * @param   string  the comment retreived using ReflectionClass->getDocComment()
+	 * [!!] 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)
+	public static function parse($comment, $html = TRUE)
 	{
 		// 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);
+		// Split into lines while capturing without leading whitespace
+		preg_match_all('/^\s*\* ?(.*)\n/m', $comment, $lines);
 
 		// Tag content
 		$tags = array();
 
-		foreach ($comment as $i => $line)
+		/**
+		 * 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)
 		{
-			// Remove all leading whitespace
-			$line = preg_replace('/^\s*\* ?/m', '', $line);
-
-			// Search this line for a tag
-			if (preg_match('/^@(\S+)(?:\s*(.+))?$/', $line, $matches))
+			// Don't show @access lines, they are shown elsewhere
+			if ($tag !== 'access')
 			{
-				// This is a tag line
-				unset($comment[$i]);
-
-				$name = $matches[1];
-				$text = isset($matches[2]) ? $matches[2] : '';
-
-				switch ($name)
+				if ($html)
 				{
-					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('/^'.Kodoc::$regex_class_member.'$/i', $text, $matches))
-						{
-							$text = Kodoc::link_class_member($matches);
-						}
-					break;
-					// Don't show @access lines, they are shown elsewhere
-					case 'access':
-						continue 2;
+					$text = Kodoc::format_tag($tag, $text);
 				}
 
 				// Add the tag
-				$tags[$name][] = $text;
+				$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
 			{
-				// Overwrite the comment line
-				$comment[$i] = (string) $line;
+				$comment .= "\n".$line;
 			}
 		}
 
-		// Concat the comment lines back to a block of text
-		if ($comment = trim(implode("\n", $comment)))
+		$comment = trim($comment, "\n");
+
+		if ($comment AND $html)
 		{
 			// Parse the comment with Markdown
-			$comment = Markdown($comment);
+			$comment = Kodoc_Markdown::markdown($comment);
 		}
 
 		return array($comment, $tags);
@@ -328,7 +377,7 @@ class Kohana_Kodoc {
 	 */
 	public static function show_class(Kodoc_Class $class)
 	{
-		$api_packages = Kohana::config('userguide.api_packages');
+		$api_packages = Kohana::$config->load('userguide.api_packages');
 
 		// If api_packages is true, all packages should be shown
 		if ($api_packages === TRUE)
@@ -350,5 +399,68 @@ class Kohana_Kodoc {
 		return $show_this;
 	}
 
+	/**
+	 * Checks whether a class is a transparent extension class or not.
+	 *
+	 * This method takes an optional $classes parameter, a list of all defined
+	 * class names. If provided, the method will return false unless the extension
+	 * class exists. If not, the method will only check known transparent class
+	 * prefixes.
+	 *
+	 * Transparent prefixes are defined in the userguide.php config file:
+	 *
+	 *     'transparent_prefixes' => array(
+	 *         'Kohana' => TRUE,
+	 *     );
+	 *
+	 * Module developers can therefore add their own transparent extension
+	 * namespaces and exclude them from the userguide.
+	 *          
+	 * @param string $class The name of the class to check for transparency
+	 * @param array $classes An optional list of all defined classes
+	 * @return false If this is not a transparent extension class 
+	 * @return string The name of the class that extends this (in the case provided)
+	 * @throws InvalidArgumentException If the $classes array is provided and the $class variable is not lowercase
+	 */
+	public static function is_transparent($class, $classes = NULL)
+	{
+
+		static $transparent_prefixes = NULL;
+
+		if ( ! $transparent_prefixes)
+		{
+			$transparent_prefixes = Kohana::$config->load('userguide.transparent_prefixes');
+		}
+
+		// Split the class name at the first underscore
+		$segments = explode('_',$class,2);
+
+		if ((count($segments) == 2) AND (isset($transparent_prefixes[$segments[0]])))
+		{
+			if ($segments[1] === 'Core')
+			{
+				// Cater for Module extends Module_Core naming
+				$child_class = $segments[0];
+			}
+			else
+			{
+				// Cater for Foo extends Module_Foo naming
+				$child_class = $segments[1];
+			}
+			
+			// It is only a transparent class if the unprefixed class also exists
+			if ($classes AND ! isset($classes[$child_class]))
+				return FALSE;
+			
+			// Return the name of the child class
+			return $child_class;
+		}
+		else
+		{
+			// Not a transparent class
+			return FALSE;
+		}
+	}
+
 
 } // End Kodoc

includes/kohana/modules/userguide/classes/Kohana/Kodoc/Class.php

@@ -5,7 +5,7 @@
  * @package    Kohana/Userguide
  * @category   Base
  * @author     Kohana Team
- * @copyright  (c) 2009 Kohana Team
+ * @copyright  (c) 2009-2012 Kohana Team
  * @license    http://kohanaphp.com/license
  */
 class Kohana_Kodoc_Class extends Kodoc {
@@ -35,6 +35,11 @@ class Kohana_Kodoc_Class extends Kodoc {
 	 */
 	public $constants = array();
 
+	/**
+	 * @var array Parent classes/interfaces of this class/interface
+	 */
+	public $parents = array();
+
 	/**
 	 * Loads a class and uses [reflection](http://php.net/reflection) to parse
 	 * the class. Reads the class modifiers, constants and comment. Parses the
@@ -52,43 +57,80 @@ class Kohana_Kodoc_Class extends Kodoc {
 			$this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
 		}
 
-		if ($constants = $this->class->getConstants())
+		$this->constants = $this->class->getConstants();
+
+		// If ReflectionClass::getParentClass() won't work if the class in 
+		// question is an interface
+		if ($this->class->isInterface())
 		{
-			foreach ($constants as $name => $value)
+			$this->parents = $this->class->getInterfaces();
+		}
+		else
+		{
+			$parent = $this->class;
+
+			while ($parent = $parent->getParentClass())
 			{
-				$this->constants[$name] = Debug::vars($value);
+				$this->parents[] = $parent;
 			}
 		}
 
-		$parent = $this->class;
-
-		do
+		if ( ! $comment = $this->class->getDocComment())
 		{
-			if ($comment = $parent->getDocComment())
+			foreach ($this->parents as $parent)
 			{
-				// Found a description for this class
-				break;
+				if ($comment = $parent->getDocComment())
+				{
+					// Found a description for this class
+					break;
+				}
 			}
 		}
-		while ($parent = $parent->getParentClass());
 
-		list($this->description, $this->tags) = Kodoc::parse($comment);
-		
+		list($this->description, $this->tags) = Kodoc::parse($comment, FALSE);
+	}
+
+	/**
+	 * Gets the constants of this class as HTML.
+	 *
+	 * @return  array
+	 */
+	public function constants()
+	{
+		$result = array();
+
+		foreach ($this->constants as $name => $value)
+		{
+			$result[$name] = Debug::vars($value);
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Get the description of this class as HTML. Includes a warning when the
+	 * class or one of its parents could not be found.
+	 *
+	 * @return  string  HTML
+	 */
+	public function description()
+	{
+		$result = $this->description;
+
 		// If this class extends Kodoc_Missing, add a warning about possible
 		// incomplete documentation
-		$parent = $this->class;
-		
-		while ($parent = $parent->getParentClass())
+		foreach ($this->parents as $parent)
 		{
 			if ($parent->name == 'Kodoc_Missing')
 			{
-				$warning = "[!!] **This class, or a class parent, could not be
+				$result .= "[!!] **This class, or a class parent, could not be
 				           found or loaded. This could be caused by a missing
-						   module or other dependancy. The documentation for
-						   class may not be complete!**";
-				$this->description = Markdown($warning).$this->description;
+				           module or other dependancy. The documentation for
+				           class may not be complete!**";
 			}
 		}
+
+		return Kodoc_Markdown::markdown($result);
 	}
 
 	/**
@@ -100,12 +142,14 @@ class Kohana_Kodoc_Class extends Kodoc {
 	{
 		$props = $this->class->getProperties();
 
+		$defaults = $this->class->getDefaultProperties();
+
 		usort($props, array($this,'_prop_sort'));
 
 		foreach ($props as $key => $property)
 		{
 			// Create Kodoc Properties for each property
-			$props[$key] = new Kodoc_Property($this->class->name, $property->name);
+			$props[$key] = new Kodoc_Property($this->class->name, $property->name,  Arr::get($defaults, $property->name));
 		}
 
 		return $props;
@@ -174,7 +218,7 @@ class Kohana_Kodoc_Class extends Kodoc {
 		
 		
 		/*
-		echo kohana::debug('a is '.$a->class.'::'.$a->name,'b is '.$b->class.'::'.$b->name,
+		echo Debug::vars('a is '.$a->class.'::'.$a->name,'b is '.$b->class.'::'.$b->name,
 						   'are the classes the same?', $a->class == $b->class,'if they are, the result is:',strcmp($a->name, $b->name),
 						   'is a this class?', $a->name == $this->class->name,-1,
 						   'is b this class?', $b->name == $this->class->name,1,
@@ -213,4 +257,23 @@ class Kohana_Kodoc_Class extends Kodoc {
 		return $bdepth - $adepth;
 	}
 
-} // End Kodac_Class
+	/**
+	 * 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;
+	}
+}

includes/kohana/modules/userguide/classes/Kohana/Kodoc/Markdown.php

@@ -5,7 +5,7 @@
  * @package    Kohana/Userguide
  * @category   Base
  * @author     Kohana Team
- * @copyright  (c) 2009 Kohana Team
+ * @copyright  (c) 2009-2012 Kohana Team
  * @license    http://kohanaphp.com/license
  */
 class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser {
@@ -38,6 +38,26 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser {
 	 */
 	public static $show_toc = false;
 	
+	/**
+	 * Transform some text using [Kodoc_Markdown]
+	 *
+	 * @see Markdown()
+	 *
+	 * @param   string  Text to parse
+	 * @return  string  Transformed text
+	 */
+	public static function markdown($text)
+	{
+		static $instance;
+
+		if ($instance === NULL)
+		{
+			$instance = new Kodoc_Markdown;
+		}
+
+		return $instance->transform($text);
+	}
+
 	public function __construct()
 	{
 		// doImage is 10, add image url just before
@@ -107,7 +127,7 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser {
 			$attr = ' id="'.$this->make_heading_id($matches[2]).'"';
 		
 		// Add this header to the page toc
-		$this->_add_to_toc($level,$matches[2],$this->make_heading_id($matches[2]));
+		$this->_add_to_toc($level, $matches[2], $this->make_heading_id(empty($matches[3]) ? $matches[2] : $matches[3]));
 		
 		$block = "<h$level$attr>".$this->runSpanGamut($matches[2])."</h$level>";
 		return "\n" . $this->hashBlock($block) . "\n\n";
@@ -152,18 +172,23 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser {
 			{
 				list($search, $view) = $set;
 
-				try
+				if (Kohana::find_file('views', $view))
 				{
-					$replace[$search] = View::factory($view)->render();
-				}
-				catch (Exception $e)
-				{
-					ob_start();
+					try
+					{
+						$replace[$search] = View::factory($view)->render();
+					}
+					catch (Exception $e)
+					{
+						/**
+						* Capture the exception handler output and insert it instead.
+						*
+						* NOTE: Is this really the correct way to handle an exception?
+						*/
+						$response = Kohana_exception::_handler($e);
 
-					// Capture the exception handler output and insert it instead
-					Kohana_exception::handler($e);
-
-					$replace[$search] = ob_get_clean();
+						$replace[$search] = $response->body();
+					}
 				}
 			}
 

includes/kohana/modules/userguide/classes/Kohana/Kodoc/Method.php

@@ -68,7 +68,7 @@ class Kohana_Kodoc_Method extends Kodoc {
 
 				if (isset($tags['param'][$i]))
 				{
-					preg_match('/^(\S+)(?:\s*(?:\$'.$param->name.'\s*)?(.+))?$/', $tags['param'][$i], $matches);
+					preg_match('/^(\S+)(?:\s*(?:\$'.$param->name.'\s*)?(.+))?$/s', $tags['param'][$i], $matches);
 
 					$param->type = $matches[1];
 
@@ -138,4 +138,4 @@ class Kohana_Kodoc_Method extends Kodoc {
 		return $out;
 	}
 
-} // End Kodoc_Method
+} // End Kodoc_Method

includes/kohana/modules/userguide/classes/Kohana/Kodoc/Method/Param.php

@@ -83,7 +83,7 @@ class Kohana_Kodoc_Method_Param extends Kodoc {
 
 		if ($this->description)
 		{
-			$display .= '<span class="param" title="'.$this->description.'">$'.$this->name.'</span> ';
+			$display .= '<span class="param" title="'.preg_replace('/\s+/', ' ', $this->description).'">$'.$this->name.'</span> ';
 		}
 		else
 		{

includes/kohana/modules/userguide/classes/Kohana/Kodoc/Property.php

@@ -5,7 +5,7 @@
  * @package    Kohana/Userguide
  * @category   Base
  * @author     Kohana Team
- * @copyright  (c) 2009 Kohana Team
+ * @copyright  (c) 2009-2012 Kohana Team
  * @license    http://kohanaphp.com/license
  */
 class Kohana_Kodoc_Property extends Kodoc {
@@ -30,7 +30,12 @@ class Kohana_Kodoc_Property extends Kodoc {
 	 */
 	public $value;
 
-	public function __construct($class, $property)
+	/**
+	 * @var  string  default value of the property
+	 */
+	public $default;
+
+	public function __construct($class, $property, $default = NULL)
 	{
 		$property = new ReflectionProperty($class, $property);
 
@@ -45,19 +50,19 @@ class Kohana_Kodoc_Property extends Kodoc {
 
 		if (isset($tags['var']))
 		{
-			if (preg_match('/^(\S*)(?:\s*(.+?))?$/', $tags['var'][0], $matches))
+			if (preg_match('/^(\S*)(?:\s*(.+?))?$/s', $tags['var'][0], $matches))
 			{
 				$this->type = $matches[1];
 
 				if (isset($matches[2]))
 				{
-					$this->description = Markdown($matches[2]);
+					$this->description = Kodoc_Markdown::markdown($matches[2]);
 				}
 			}
 		}
 
 		$this->property = $property;
-		
+
 		// Show the value of static properties, but only if they are public or we are php 5.3 or higher and can force them to be accessible
 		if ($property->isStatic() AND ($property->isPublic() OR version_compare(PHP_VERSION, '5.3', '>=')))
 		{
@@ -66,7 +71,7 @@ class Kohana_Kodoc_Property extends Kodoc {
 			{
 				$property->setAccessible(TRUE);
 			}
-			
+
 			// Don't debug the entire object, just say what kind of object it is
 			if (is_object($property->getValue($class)))
 			{
@@ -77,7 +82,9 @@ class Kohana_Kodoc_Property extends Kodoc {
 				$this->value = Debug::vars($property->getValue($class));
 			}
 		}
-		
+
+		// Store the defult property
+		$this->default = Debug::vars($default);;
 	}
 
 } // End Kodoc_Property