From f0082206c4a80447b56eb573d215308b140cbe8b Mon Sep 17 00:00:00 2001 From: "T. Zengerink" Date: Wed, 16 Jan 2013 14:52:45 +0100 Subject: [PATCH] Improved documentation comments - Consistent copyright (2012 -> 2013) - Fixed incorrect license link --- classes/Kohana/Controller/Userguide.php | 60 +++++++++++++------------- classes/Kohana/Kodoc.php | 21 +++++---- classes/Kohana/Kodoc/Class.php | 36 ++++++++-------- classes/Kohana/Kodoc/Markdown.php | 75 +++++++++++++++++---------------- classes/Kohana/Kodoc/Method.php | 12 +++--- classes/Kohana/Kodoc/Method/Param.php | 4 +- classes/Kohana/Kodoc/Missing.php | 2 + classes/Kohana/Kodoc/Property.php | 4 +- config/userguide.php | 8 ++-- tests/KodocTest.php | 10 ++--- tests/userguide/ControllerTest.php | 7 +-- 11 files changed, 123 insertions(+), 116 deletions(-) diff --git a/classes/Kohana/Controller/Userguide.php b/classes/Kohana/Controller/Userguide.php index 1c4c10e..6f8f295 100644 --- a/classes/Kohana/Controller/Userguide.php +++ b/classes/Kohana/Controller/Userguide.php @@ -3,8 +3,10 @@ * Kohana user guide and api browser. * * @package Kohana/Userguide - * @category Controllers + * @category Controller * @author Kohana Team + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ abstract class Kohana_Controller_Userguide extends Controller_Template { @@ -38,7 +40,7 @@ abstract class Kohana_Controller_Userguide extends Controller_Template { // 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() { @@ -46,18 +48,18 @@ abstract class Kohana_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->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->show_comments = FALSE; @@ -108,19 +110,19 @@ abstract class Kohana_Controller_Userguide extends Controller_Template { { return $this->index(); } - + // If this module's userguide pages are disabled, show the error page if ( ! Kohana::$config->load('userguide.modules.'.$module.'.enabled')) { 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'); } - + // If a module is set, but no page was provided in the url, show the index page if ( ! $page ) { @@ -135,7 +137,7 @@ abstract class Kohana_Controller_Userguide extends Controller_Template { { 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.'/'; @@ -153,7 +155,7 @@ abstract class Kohana_Controller_Userguide extends Controller_Template { // Bind the breadcrumb $this->template->bind('breadcrumb', $breadcrumb); - + // Bind the copyright $this->template->copyright = Kohana::$config->load('userguide.modules.'.$module.'.copyright'); @@ -161,9 +163,9 @@ abstract class Kohana_Controller_Userguide extends Controller_Template { $breadcrumb = array(); $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') { @@ -193,7 +195,7 @@ abstract class Kohana_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) @@ -208,7 +210,7 @@ abstract class Kohana_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 api_packages config setting.'); - + // Everything is fine, display the class. $this->template->title = $class; @@ -245,7 +247,7 @@ abstract class Kohana_Controller_Userguide extends Controller_Template { { // Check if the browser sent an "if-none-match: " header, and tell if the file hasn't changed $this->check_cache(sha1($this->request->uri()).filemtime($file)); - + // Send the file content as the response $this->response->body(file_get_contents($file)); @@ -323,66 +325,66 @@ abstract class Kohana_Controller_Userguide extends Controller_Template { 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 Debug::vars($text); - + //$text = preg_replace('/(\s*[\-\*\+]\s*)(.*)/','$1$2',$text); $text = preg_replace('/^(\s*[\-\*\+]\s*)([^\[\]]+)$/m','$1$2',$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->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) { @@ -391,7 +393,7 @@ abstract class Kohana_Controller_Userguide extends Controller_Template { unset($modules[$key]); } } - + return $modules; } diff --git a/classes/Kohana/Kodoc.php b/classes/Kohana/Kodoc.php index acd9cbc..24a6b28 100644 --- a/classes/Kohana/Kodoc.php +++ b/classes/Kohana/Kodoc.php @@ -5,8 +5,8 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2008-2012 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc { @@ -415,12 +415,12 @@ class Kohana_Kodoc { * * 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 + * + * @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) { @@ -447,11 +447,11 @@ class Kohana_Kodoc { // 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; } @@ -462,5 +462,4 @@ class Kohana_Kodoc { } } - } // End Kodoc diff --git a/classes/Kohana/Kodoc/Class.php b/classes/Kohana/Kodoc/Class.php index 2c2f2f2..9ef9b16 100644 --- a/classes/Kohana/Kodoc/Class.php +++ b/classes/Kohana/Kodoc/Class.php @@ -5,8 +5,8 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2009-2012 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc_Class extends Kodoc { @@ -45,7 +45,7 @@ class Kohana_Kodoc_Class extends Kodoc { * the class. Reads the class modifiers, constants and comment. Parses the * comment to find the description and tags. * - * @param string class name + * @param string Class name * @return void */ public function __construct($class) @@ -59,7 +59,7 @@ class Kohana_Kodoc_Class extends Kodoc { $this->constants = $this->class->getConstants(); - // If ReflectionClass::getParentClass() won't work if the class in + // If ReflectionClass::getParentClass() won't work if the class in // question is an interface if ($this->class->isInterface()) { @@ -154,7 +154,7 @@ class Kohana_Kodoc_Class extends Kodoc { return $props; } - + protected function _prop_sort($a, $b) { // If one property is public, and the other is not, it goes on top @@ -162,13 +162,13 @@ class Kohana_Kodoc_Class extends Kodoc { return -1; if ($b->isPublic() AND ( ! $a->isPublic())) return 1; - + // If one property is protected and the other is private, it goes on top if ($a->isProtected() AND $b->isPrivate()) return -1; if ($b->isProtected() AND $a->isPrivate()) return 1; - + // Otherwise just do alphabetical return strcmp($a->name, $b->name); } @@ -191,14 +191,15 @@ class Kohana_Kodoc_Class extends Kodoc { return $methods; } - + /** * Sort methods based on their visibility and declaring class based on: - * - methods will be sorted public, protected, then private. - * - methods that are declared by an ancestor will be after classes + * + * * methods will be sorted public, protected, then private. + * * methods that are declared by an ancestor will be after classes * declared by the current class - * - lastly, they will be sorted alphabetically - * + * * lastly, they will be sorted alphabetically + * */ protected function _method_sort($a, $b) { @@ -207,16 +208,16 @@ class Kohana_Kodoc_Class extends Kodoc { return -1; if ($b->isPublic() AND ( ! $a->isPublic())) return 1; - + // If one method is protected and the other is private, it goes on top if ($a->isProtected() AND $b->isPrivate()) return -1; if ($b->isProtected() AND $a->isPrivate()) return 1; - + // The methods have the same visibility, so check the declaring class depth: - - + + /* 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), @@ -276,4 +277,5 @@ class Kohana_Kodoc_Class extends Kodoc { return $result; } -} + +} // End Kodoc_Class diff --git a/classes/Kohana/Kodoc/Markdown.php b/classes/Kohana/Kodoc/Markdown.php index 856be95..2c48862 100644 --- a/classes/Kohana/Kodoc/Markdown.php +++ b/classes/Kohana/Kodoc/Markdown.php @@ -5,8 +5,8 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2009-2012 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { @@ -19,25 +19,26 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { * @var string base url for images */ public static $image_url = ''; - + /** - * Currently defined heading ids. + * Currently defined heading ids. * Used to prevent creating multiple headings with same id. - * @var array + * + * @var array */ protected $_heading_ids = array(); - + /** * @var string the generated table of contents */ protected static $_toc = ""; - + /** * Slightly less terrible way to make it so the TOC only shows up when we * want it to. set this to true to show the toc. */ public static $show_toc = false; - + /** * Transform some text using [Kodoc_Markdown] * @@ -81,82 +82,82 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { // PHP4 makes me sad. parent::MarkdownExtra_Parser(); } - + /** * Callback for the heading setext style - * + * * Heading 1 * ========= * - * @param array Matches from regex call - * @return string Generated html + * @param array Matches from regex call + * @return string Generated html */ - function _doHeaders_callback_setext($matches) + function _doHeaders_callback_setext($matches) { if ($matches[3] == '-' && preg_match('{^- }', $matches[1])) return $matches[0]; $level = $matches[3]{0} == '=' ? 1 : 2; $attr = $this->_doHeaders_attr($id =& $matches[2]); - + // Only auto-generate id if one doesn't exist if(empty($attr)) $attr = ' id="'.$this->make_heading_id($matches[1]).'"'; - + // Add this header to the page toc $this->_add_to_toc($level,$matches[1],$this->make_heading_id($matches[1])); - + $block = "".$this->runSpanGamut($matches[1]).""; return "\n" . $this->hashBlock($block) . "\n\n"; } - + /** * Callback for the heading atx style * * # Heading 1 * - * @param array Matches from regex call - * @return string Generated html + * @param array Matches from regex call + * @return string Generated html */ - function _doHeaders_callback_atx($matches) + function _doHeaders_callback_atx($matches) { $level = strlen($matches[1]); $attr = $this->_doHeaders_attr($id =& $matches[3]); - + // Only auto-generate id if one doesn't exist if(empty($attr)) $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(empty($matches[3]) ? $matches[2] : $matches[3])); - + $block = "".$this->runSpanGamut($matches[2]).""; return "\n" . $this->hashBlock($block) . "\n\n"; } - + /** * Makes a heading id from the heading text * If any heading share the same name then subsequent headings will have an integer appended * - * @param string The heading text - * @return string ID for the heading + * @param string The heading text + * @return string ID for the heading */ function make_heading_id($heading) { $id = url::title($heading, '-', TRUE); - + if(isset($this->_heading_ids[$id])) { $id .= '-'; - + $count = 0; - + while (isset($this->_heading_ids[$id]) AND ++$count) { $id .= $count; } - } - + } + return $id; } @@ -203,7 +204,7 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { * * [filesystem](about.filesystem "Optional title") * - * @param string span text + * @param string Span text * @return string */ public function doBaseURL($text) @@ -217,7 +218,7 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { * * ![Install Page](img/install.png "Optional title") * - * @param string span text + * @param string Span text * @return string */ public function doImageURL($text) @@ -231,7 +232,7 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { * * [Class_Name], [Class::method] or [Class::$property] * - * @param string span text + * @param string Span text * @return string */ public function doAPI($text) @@ -244,7 +245,7 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { * * [!!] Remember the milk! * - * @param string span text + * @param string Span text * @return string */ public function doNotes($text) @@ -256,7 +257,7 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { return $this->hashBlock('

'.$match[1].'

'); } - + protected function _add_to_toc($level, $name, $id) { self::$_toc[] = array( @@ -264,7 +265,7 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { 'name' => $name, 'id' => $id); } - + public function doTOC($text) { // Only add the toc do userguide pages, not api since they already have one diff --git a/classes/Kohana/Kodoc/Method.php b/classes/Kohana/Kodoc/Method.php index 2e673d4..8b26cc2 100644 --- a/classes/Kohana/Kodoc/Method.php +++ b/classes/Kohana/Kodoc/Method.php @@ -5,28 +5,28 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2009 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc_Method extends Kodoc { /** - * @var ReflectionMethod The ReflectionMethod for this class + * @var ReflectionMethod The ReflectionMethod for this class */ public $method; /** - * @var array array of Kodoc_Method_Param + * @var array Array of Kodoc_Method_Param */ public $params; /** - * @var array the things this function can return + * @var array The things this function can return */ public $return = array(); /** - * @var string the source code for this function + * @var string The source code for this function */ public $source; diff --git a/classes/Kohana/Kodoc/Method/Param.php b/classes/Kohana/Kodoc/Method/Param.php index 7b5976f..a29c0e2 100644 --- a/classes/Kohana/Kodoc/Method/Param.php +++ b/classes/Kohana/Kodoc/Method/Param.php @@ -5,8 +5,8 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2009 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc_Method_Param extends Kodoc { diff --git a/classes/Kohana/Kodoc/Missing.php b/classes/Kohana/Kodoc/Missing.php index b3ebcdf..85e841b 100644 --- a/classes/Kohana/Kodoc/Missing.php +++ b/classes/Kohana/Kodoc/Missing.php @@ -7,6 +7,8 @@ * @package Kohana/Userguide * @category Undocumented * @author Kohana Team + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license * @since 3.0.7 */ abstract class Kohana_Kodoc_Missing { diff --git a/classes/Kohana/Kodoc/Property.php b/classes/Kohana/Kodoc/Property.php index af2cbee..a4b5bef 100644 --- a/classes/Kohana/Kodoc/Property.php +++ b/classes/Kohana/Kodoc/Property.php @@ -5,8 +5,8 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2009-2012 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc_Property extends Kodoc { diff --git a/config/userguide.php b/config/userguide.php index 0258f69..eae38c2 100644 --- a/config/userguide.php +++ b/config/userguide.php @@ -20,16 +20,16 @@ return array // Whether this modules userguide pages should be shown 'enabled' => TRUE, - + // The name that should show up on the userguide index page 'name' => 'Userguide', // A short description of this module, shown on the index page 'description' => 'Documentation viewer and api generation.', - + // Copyright message, shown in the footer for this module - 'copyright' => '© 2008–2012 Kohana Team', - ) + 'copyright' => '© 2008–2013 Kohana Team', + ) ), // Set transparent class name segments diff --git a/tests/KodocTest.php b/tests/KodocTest.php index 8258f51..1432547 100644 --- a/tests/KodocTest.php +++ b/tests/KodocTest.php @@ -6,7 +6,7 @@ * * @package Kohana/Userguide * @author Kohana Team - * @copyright (c) 2012 Kohana Team + * @copyright (c) 2008-2013 Kohana Team * @license http://kohanaframework.org/license */ class Kohana_KodocTest extends PHPUnit_Framework_TestCase @@ -88,7 +88,7 @@ COMMENT array( <<<'COMMENT' /** - * @trailingspace + * @trailingspace */ COMMENT , @@ -162,11 +162,11 @@ COMMENT array( <<<'COMMENT' /** - * @copyright (c) 2012 Kohana Team + * @copyright (c) 2008-2013 Kohana Team */ COMMENT , - array('', array('copyright' => array('© 2012 Kohana Team'))), + array('', array('copyright' => array('© 2008-2013 Kohana Team'))), ), array( <<<'COMMENT' @@ -328,7 +328,7 @@ COMMENT { $this->assertSame($expected, Kodoc::parse($comment)); } - + /** * Provides test data for test_transparent_classes * @return array diff --git a/tests/userguide/ControllerTest.php b/tests/userguide/ControllerTest.php index 30ef475..d9f1313 100644 --- a/tests/userguide/ControllerTest.php +++ b/tests/userguide/ControllerTest.php @@ -10,7 +10,7 @@ * @package Kohana/Userguide * @category Tests * @author Kohana Team - * @copyright (c) 2008-2012 Kohana Team + * @copyright (c) 2008-2013 Kohana Team * @license http://kohanaframework.org/license */ class Userguide_ControllerTest extends Unittest_TestCase @@ -28,8 +28,8 @@ class Userguide_ControllerTest extends Unittest_TestCase /** * @dataProvider provider_file_finds_markdown_files - * @param string $page Page name passed in the URL - * @param string $expected_file Expected result from Controller_Userguide::file + * @param string $page Page name passed in the URL + * @param string $expected_file Expected result from Controller_Userguide::file */ public function test_file_finds_markdown_files($page, $expected_file) { @@ -42,4 +42,5 @@ class Userguide_ControllerTest extends Unittest_TestCase $this->assertEquals($expected_file, $file); } + } -- 2.11.4.GIT