From f27fa1f314d46042df9129eadf54ae9f9de8f3bc Mon Sep 17 00:00:00 2001
From: Shish <shish@shishnet.org>
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 @@
<?php
/**
- * @package SCore
+ * \page events 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. Since events can store data, they can be used to
+ * return data to the extension which sent them, for example:
+ *
+ * \code
+ * $tfe = new TextFormattingEvent($original_text);
+ * send_event($tfe);
+ * $formatted_text = $tfe->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 @@
<?php
/**
- * @package SCore
+ * \page themes Themes
+ *
+ * Each extension has a theme with a specific name -- eg. the extension Setup
+ * which is stored in ext/setup/main.php will have a theme called SetupTheme
+ * stored in ext/setup/theme.php. If you want to customise it, create a class
+ * in the file themes/mytheme/setup.theme.php called CustomSetupTheme which
+ * extends SetupTheme 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.
*/
+
/**
* A data structure for holding all the bits of data that make up a page.
*
diff --git a/core/util.inc.php b/core/util.inc.php
index 29c9965f..8ff3723f 100644
--- a/core/util.inc.php
+++ b/core/util.inc.php
@@ -11,7 +11,7 @@
/**
* Make some data safe for printing into HTML
*
- * @var string
+ * @retval string
*/
function html_escape($input) {
return htmlentities($input, ENT_QUOTES, "UTF-8");
@@ -20,7 +20,7 @@ function html_escape($input) {
/**
* Make sure some data is safe to be used in integer context
*
- * @var int
+ * @retval int
*/
function int_escape($input) {
return (int)$input;
@@ -29,7 +29,7 @@ function int_escape($input) {
/**
* Make sure some data is safe to be used in URL context
*
- * @var string
+ * @retval string
*/
function url_escape($input) {
$input = str_replace('^', '^^', $input);
@@ -41,7 +41,7 @@ function url_escape($input) {
/**
* Make sure some data is safe to be used in SQL context
*
- * @var string
+ * @retval string
*/
function sql_escape($input) {
global $database;
@@ -51,7 +51,7 @@ function sql_escape($input) {
/**
* Turn a human readable filesize into an integer, eg 1KB -> 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 <<<EOD
+ print "
Currently SCore Engine doesn't support versions of PHP lower than 5.0.0 --
PHP4 and earlier are officially dead according to their creators,
please tell your host to upgrade.
-EOD;
+";
exit;
}
}
/**
- * @ignore
+ * @private
*/
function check_cli() {
if(isset($_SERVER['REMOTE_ADDR'])) {
@@ -171,7 +175,7 @@ function check_cli() {
/**
* $db is the connection object
*
- * @ignore
+ * @private
*/
function _count_execs($db, $sql, $inputarray) {
global $_execs;
@@ -213,7 +217,7 @@ function get_theme_object(Extension $class, $fatal=true) {
/**
* Compare two Block objects, used to sort them before being displayed
*
- * @var int
+ * @retval int
*/
function blockcmp($a, $b) {
if($a->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 @@
<?php
-/* AdminBuildingEvent {{{
- *
+/**
* Sent when the admin page is ready to be added to
*/
class AdminBuildingEvent extends Event {
@@ -9,7 +8,6 @@ class AdminBuildingEvent extends Event {
$this->page = $page;
}
}
-// }}}
class AdminPage implements Extension {
var $theme;
diff --git a/index.php b/index.php
index abdbcf42..6380ae79 100644
--- a/index.php
+++ b/index.php
@@ -1,4 +1,25 @@
<?php
+/**
+ * \mainpage Shimmie2 / SCore Documentation
+ *
+ * There are a bunch of Extension subclasses, they talk to eachother by sending
+ * and recieving Event subclasses. The topic of conversation is decided by the
+ * initial PageRequestEvent, and each extension puts its notes into the shared
+ * Page data store. Once the conversation is over, the Page is passed to the
+ * current theme's Layout class which will tidy up the data and present it to
+ * the user.
+ *
+ *
+ * \page globals Globals
+ *
+ * There are four global variables which are pretty essential to most extensions:
+ *
+ * \li $config -- some variety of Config subclass
+ * \li $database -- a Database object used to get raw SQL access
+ * \li $page -- a Page to holds all the loose bits of extension output
+ * \li $user -- the currently logged in User
+ */
+
// set up and purify the environment
define("DEBUG", true);
define("SCORE_VERSION", 's2hack');
@@ -10,8 +31,8 @@ if(!file_exists("config.php")) {
}
require_once "core/util.inc.php";
-version_check();
-sanitise_environment();
+_version_check();
+_sanitise_environment();
try {