docs

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;

core/README

@@ -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.
-
-
-

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 {}
 

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()
  */
 
 /**

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                                                                   *
 \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

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.
  *

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
+ * @private
- */
-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
  */
 function weighted_random($weights) {
 	$total = 0;
@@ -493,9 +477,7 @@ function weighted_random($weights) {
 * Event API                                                                 *
 \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/**
+/** @private */
- * @ignore
- */
 $_event_listeners = array();
 
 /**
@@ -509,9 +491,7 @@ function add_event_listener(Extension $extension, $pos=50) {
 	$_event_listeners[$pos] = $extension;
 }
 
-/**
+/** @private */
- * @ignore
- */
 $_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;

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;

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();
+_version_check();
-sanitise_environment();
+_sanitise_environment();
 
 
 try {