From 383dd0088eb55c7fb59cddd874afb2b5be2d03f6 Mon Sep 17 00:00:00 2001
From: Shish <shish@shishnet.org>
Date: Mon, 5 Mar 2012 13:56:36 +0000
Subject: [PATCH] documentation updates

---
 core/extension.class.php | 24 +++++++++++++++++++++---
 index.php                | 15 ++++-----------
 2 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/core/extension.class.php b/core/extension.class.php
index 6798df29..e7a0f294 100644
--- a/core/extension.class.php
+++ b/core/extension.class.php
@@ -20,17 +20,27 @@
  *
  * \code
  * // ext/hello/main.php
+ * public class HelloEvent extends Event {
+ *     public function __construct($username) {
+ *         $this->username = $username;
+ *     }
+ * }
+ * 
  * public class Hello extends Extension {
  *     public void onPageRequest(PageRequestEvent $event) {
  *         global $page, $user;
- *         $this->theme->display_hello($page, $user);
+ *         send_event(new HelloEvent($user->name));
+ *     }
+ *     public void onHello(HelloEvent $event) {
+ *         $this->theme->display_hello($event->username);
  *     }
  * }
  *
  * // ext/hello/theme.php
  * public class HelloTheme extends Themelet {
- *     public void display_hello(Page $page, User $user) {
- *         $page->add_block(new Block("Hello!", "Hello there ".html_escape($user->name));
+ *     public void display_hello($username) {
+ *         global $page;
+ *         $page->add_block(new Block("Hello!", "Hello there ".html_escape($username));
  *     }
  * }
  *
@@ -67,17 +77,25 @@
  * find the thread where the original was posted >_<
  */
 abstract class Extension {
+	/** this theme's Themelet object */
 	var $theme;
+
+	/** @private */
 	var $_child;
 
 	// in PHP5.3, late static bindings can take care of this; __CLASS__
 	// used here will refer to the subclass
 	// http://php.net/manual/en/language.oop5.late-static-bindings.php
+	/** @private */
 	public function i_am(Extension $child) {
 		$this->_child = $child;
 		if(is_null($this->theme)) $this->theme = get_theme_object($child, false);
 	}
 
+	/**
+	 * Override this to change the priority of the extension,
+	 * lower numbered ones will recieve events first
+	 */
 	public function get_priority() {
 		return 50;
 	}
diff --git a/index.php b/index.php
index 8fff3a58..06663820 100644
--- a/index.php
+++ b/index.php
@@ -12,20 +12,14 @@
  * which links to images on an image board, with no wiki or messaging, and so
  * on and so on...
  * 
- * To learn about the innards of SCore, start with the \ref overview.
- *
- *
- * \page overview High Level Overview
- *
  * Dijkstra will kill me for personifying my architecture, but I can't think
  * of a better way without going into all the little details.
- *
  * 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
+ * and recieving Event subclasses. The primary driver for each conversation is the
+ * initial PageRequestEvent. If an Extension wants to display something to the
+ * user, it adds a block to the 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.
+ * the user. To see this in a more practical sense, see \ref hello.
  *
  * To learn more about the architecture:
  *
@@ -36,7 +30,6 @@
  *
  * \li \ref scglobals
  * \li \ref unittests
- * \li \ref hello
  *
  * \page scglobals SCore Globals
  *