From 2471a8e2eb54287a53cb591373ea83d7d81fbce8 Mon Sep 17 00:00:00 2001 From: Shish Date: Tue, 21 Jul 2009 04:18:40 +0100 Subject: [PATCH] docs --- contrib/simpletest/main.php | 14 ++++ core/README | 43 ------------- core/event.class.php | 4 +- core/extension.class.php | 21 +++++- core/imageboard.pack.php | 15 +++++ core/page.class.php | 14 +++- core/util.inc.php | 123 +++++++++++++++++------------------- ext/admin/main.php | 4 +- index.php | 25 +++++++- 9 files changed, 146 insertions(+), 117 deletions(-) delete mode 100644 core/README diff --git a/contrib/simpletest/main.php b/contrib/simpletest/main.php index 377efa93..96a49bdd 100644 --- a/contrib/simpletest/main.php +++ b/contrib/simpletest/main.php @@ -6,6 +6,19 @@ * Description: adds unit testing to SCore */ +/** + * \page unittests Unit Tests + * + * Each extension should (although doesn't technically have to) come with a + * test.php file, for example ext/index/test.php. The SimpleSCoreTest + * extension will look for these files and load any ScoreWebTestCase classes + * it finds inside them, then run them and report whether or not the test + * passes. + * + * For Shimmie2 specific extensions, there is a ShimmieWebTestCase class which + * includes functions to upload and delete images. + */ + require_once('simpletest/web_tester.php'); require_once('simpletest/unit_tester.php'); require_once('simpletest/reporter.php'); @@ -81,6 +94,7 @@ class ShimmieWebTestCase extends SCoreWebTestCase { } } +/** @private */ class TestFinder extends TestSuite { function TestFinder($hint) { if(strpos($hint, "..") !== FALSE) return; diff --git a/core/README b/core/README deleted file mode 100644 index f308d11b..00000000 --- a/core/README +++ /dev/null @@ -1,43 +0,0 @@ - -The Highest Level -~~~~~~~~~~~~~~~~~ -index.php takes care of loading the globals: - -$config -- some variety of Config class -$database -- a class used to get raw SQL access -$page -- a GenericPage object, a data structure which holds all the page parts -$user -- the currently logged in User - -then it sends an InitExtEvent and PageRequestEvent, these can each trigger -more events of their own. - -Once the chain of events comes to an end, the $page object is passed -to the theme's layout.class.php to be turned into HTML - - -Events and Extensions -~~~~~~~~~~~~~~~~~~~~~ -An event is a little blob of data saying "something happened", possibly -"something happened, here's the specific data". Events are sent with the -send_event() function. - -An extension is something which is capable of reacting to events. They -register themselves using the add_event_listener() command. (Although for -subclasses of SimpleExtension, registration is handled automatically). - - -Themes -~~~~~~ -Each extension has a theme with a specific name -- the extension Cake which -is stored in ext/cake/main.php will have a theme called CakeTheme stored in -ext/cake/theme.php. If you want to customise it, create a class in the file -themes/mytheme/cake.theme.php called CustomCakeTheme which extends CakeTheme -and overrides some of its methods. - -Generally an extension should only deal with processing data; whenever it -wants to display something, it should pass the $page data structure along -with the data to be displayed to the theme object, and the theme will add -the data into the page. - - - diff --git a/core/event.class.php b/core/event.class.php index 376f32be..2508cd10 100644 --- a/core/event.class.php +++ b/core/event.class.php @@ -14,7 +14,9 @@ abstract class Event { /** - * A wake-up call for extensions + * A wake-up call for extensions. Upon recieving an InitExtEvent an extension + * should check that it's database tables are there and install them if not, + * and set any defaults with Config::set_default_int() and such. */ class InitExtEvent extends Event {} diff --git a/core/extension.class.php b/core/extension.class.php index 2e605484..48c85b4f 100644 --- a/core/extension.class.php +++ b/core/extension.class.php @@ -1,6 +1,25 @@ formatted; + * \endcode + * + * An extension is something which is capable of reacting to events. They + * register themselves using the add_event_listener() function, after which + * events will be sent to the object's recieve_event() function. + * + * SimpleExtension subclasses are slightly different -- they are registered + * automatically, and events are sent to a named method, eg PageRequestEvent + * will be sent to onPageRequest() */ /** diff --git a/core/imageboard.pack.php b/core/imageboard.pack.php index 17cea819..e8069a47 100644 --- a/core/imageboard.pack.php +++ b/core/imageboard.pack.php @@ -6,6 +6,21 @@ * @package SCore */ +/** + * \page search Shimmie2: Searching + * + * The current search system is built of several search item -> image ID list + * translators, eg: + * + * \li the item "fred" will search the image_tags table to find image IDs with the fred tag + * \li the item "size=640x480" will search the images table to find image IDs of 640x480 images + * + * So the search "fred size=640x480" will calculate two lists and take the + * intersection. (There are some optimisations in there making it more + * complicated behind the scenes, but as long as you can turn a single word + * into a list of image IDs, making a search plugin should be simple) + */ + /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\ * Classes * \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ diff --git a/core/page.class.php b/core/page.class.php index 3686d3a9..e3e905c7 100644 --- a/core/page.class.php +++ b/core/page.class.php @@ -1,8 +1,20 @@ 1024 * - * @var int + * @retval int */ function parse_shorthand_int($limit) { if(is_numeric($limit)) { @@ -77,7 +77,7 @@ function parse_shorthand_int($limit) { /** * Turn an integer into a human readable filesize, eg 1024 -> 1KB * - * @var string + * @retval string */ function to_shorthand_int($int) { if($int >= pow(1024, 3)) { @@ -103,7 +103,7 @@ function to_shorthand_int($int) { * Figure out the correct way to link to a page, taking into account * things like the nice URLs setting * - * @var string + * @retval string */ function make_link($page=null, $query=null) { global $config; @@ -132,6 +132,10 @@ function make_link($page=null, $query=null) { } } +/** + * Make a link to a static file in the current theme's + * directory + */ function theme_file($filepath) { global $config; $theme = $config->get_string("theme","default"); @@ -144,21 +148,21 @@ function theme_file($filepath) { \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /** - * @ignore + * @private */ -function version_check() { +function _version_check() { if(version_compare(PHP_VERSION, "5.0.0") == -1) { - print <<position == $b->position) { @@ -227,7 +231,7 @@ function blockcmp($a, $b) { /** * Figure out PHP's internal memory limit * - * @var int + * @retval int */ function get_memory_limit() { global $config; @@ -257,7 +261,7 @@ function get_memory_limit() { * Get the currently active IP, masked to make it not change when the last * octet or two change, for use in session cookies and such * - * @var string + * @retval string */ function get_session_ip($config) { $mask = $config->get_string("session_hash_mask", "255.255.0.0"); @@ -271,7 +275,7 @@ function get_session_ip($config) { * * PHP really, really sucks. * - * @var string + * @retval string */ function get_base_href() { $possible_vars = array('SCRIPT_NAME', 'PHP_SELF', 'PATH_INFO', 'ORIG_PATH_INFO'); @@ -292,7 +296,7 @@ function get_base_href() { * A shorthand way to send a TextFormattingEvent and get the * results * - * @var string + * @retval string */ function format_text($string) { $tfe = new TextFormattingEvent($string); @@ -312,10 +316,16 @@ if(!defined("LOG_INFO")) define("LOG_INFO", 20); if(!defined("LOG_DEBUG")) define("LOG_DEBUG", 10); if(!defined("LOG_NOTSET")) define("LOG_NOTSET", 0); +/** + * A shorthand way to send a LogEvent + */ function log_msg($section, $priority, $message) { send_event(new LogEvent($section, $priority, $message)); } +/** + * A shorthand way to send a LogEvent + */ function log_info($section, $message) { log_msg($section, LOG_INFO, $message); } @@ -328,7 +338,7 @@ function log_info($section, $message) { /** * Remove an item from an array * - * @var array + * @retval array */ function array_remove($array, $to_remove) { $array = array_unique($array); @@ -344,7 +354,7 @@ function array_remove($array, $to_remove) { /** * Add an item to an array * - * @var array + * @retval array */ function array_add($array, $element) { $array[] = $element; @@ -355,7 +365,7 @@ function array_add($array, $element) { /** * Return the unique elements of an array, case insensitively * - * @var array + * @retval array */ function array_iunique($array) { $ok = array(); @@ -378,7 +388,7 @@ function array_iunique($array) { * * from http://uk.php.net/network * - * @var bool + * @retval bool */ function ip_in_range($IP, $CIDR) { list ($net, $mask) = split ("/", $CIDR); @@ -446,33 +456,7 @@ function full_copy($source, $target) { } /** - * @ignore - */ -function stripslashes_r($arr) { - return is_array($arr) ? array_map('stripslashes_r', $arr) : stripslashes($arr); -} - -/** - * @ignore - */ -function sanitise_environment() { - if(DEBUG) { - error_reporting(E_ALL); - assert_options(ASSERT_ACTIVE, 1); - assert_options(ASSERT_BAIL, 1); - } - - ob_start(); - - if(get_magic_quotes_gpc()) { - $_GET = stripslashes_r($_GET); - $_POST = stripslashes_r($_POST); - $_COOKIE = stripslashes_r($_COOKIE); - } -} - -/** - * @ignore + * @private */ function weighted_random($weights) { $total = 0; @@ -493,9 +477,7 @@ function weighted_random($weights) { * Event API * \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/** - * @ignore - */ +/** @private */ $_event_listeners = array(); /** @@ -509,9 +491,7 @@ function add_event_listener(Extension $extension, $pos=50) { $_event_listeners[$pos] = $extension; } -/** - * @ignore - */ +/** @private */ $_event_count = 0; /** @@ -605,13 +585,33 @@ function print_GET() { * Request initialisation stuff * \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/** @privatesection */ + +function _stripslashes_r($arr) { + return is_array($arr) ? array_map('stripslashes_r', $arr) : stripslashes($arr); +} + +function _sanitise_environment() { + if(DEBUG) { + error_reporting(E_ALL); + assert_options(ASSERT_ACTIVE, 1); + assert_options(ASSERT_BAIL, 1); + } + + ob_start(); + + if(get_magic_quotes_gpc()) { + $_GET = _stripslashes_r($_GET); + $_POST = _stripslashes_r($_POST); + $_COOKIE = _stripslashes_r($_COOKIE); + } +} + /** * Turn ^^ into ^ and ^s into / * * Necessary because various servers and various clients * think that / is special... - * - * @ignore */ function _decaret($str) { $out = ""; @@ -628,9 +628,6 @@ function _decaret($str) { return $out; } -/** - * @ignore - */ function _get_query_parts() { if(isset($_GET["q"])) { $path = $_GET["q"]; @@ -660,9 +657,6 @@ function _get_query_parts() { } } -/** - * @ignore - */ function _get_page_request() { global $config; $args = _get_query_parts(); @@ -674,9 +668,6 @@ function _get_page_request() { return new PageRequestEvent($args); } -/** - * @ignore - */ function _get_user() { global $config, $database; $user = null; diff --git a/ext/admin/main.php b/ext/admin/main.php index 522b4fab..600c9b8d 100644 --- a/ext/admin/main.php +++ b/ext/admin/main.php @@ -1,6 +1,5 @@ page = $page; } } -// }}} class AdminPage implements Extension { var $theme; diff --git a/index.php b/index.php index 646e48be..ad726be0 100644 --- a/index.php +++ b/index.php @@ -1,4 +1,25 @@