More PHP Doc comments.

core/imageboard.pack.php

@@ -139,7 +139,7 @@ class Image {
 	 * @param int $limit
 	 * @param string[] $tags
 	 * @throws SCoreException
-	 * @return Array
+	 * @return Image[]
 	 */
 	public static function find_images(/*int*/ $start, /*int*/ $limit, $tags=array()) {
 		assert(is_numeric($start));

ext/emoticons/main.php

@@ -13,18 +13,32 @@
  *  add more emoticons by uploading images into that folder.
  */
 
+/**
+ * Class Emoticons
+ */
 class Emoticons extends FormatterExtension {
+	/**
+	 * @param string $text
+	 * @return string
+	 */
 	public function format(/*string*/ $text) {
 		$data_href = get_base_href();
 		$text = preg_replace("/:([a-z]*?):/s", "<img src='$data_href/ext/emoticons/default/\\1.gif'>", $text);
 		return $text;
 	}
 
+	/**
+	 * @param string $text
+	 * @return string
+	 */
 	public function strip(/*string*/ $text) {
 		return $text;
 	}
 }
 
+/**
+ * Class EmoticonList
+ */
 class EmoticonList extends Extension {
 	public function onPageRequest(PageRequestEvent $event) {
 		if($event->page_matches("emote/list")) {

ext/emoticons/theme.php

@@ -1,5 +1,8 @@
 <?php
 class EmoticonListTheme extends Themelet {
+	/**
+	 * @param array $list
+	 */
 	public function display_emotes(/*array*/ $list) {
 		global $page;
 		$data_href = get_base_href();

ext/random_image/theme.php

@@ -1,20 +1,31 @@
 <?php
 
-class RandomImageTheme extends Themelet {
+class RandomImageTheme extends Themelet
-	public function display_random(Page $page, Image $image) {
+{
+	/**
+	 * @param Page $page
+	 * @param Image $image
+	 */
+	public function display_random(Page $page, Image $image)
+	{
 		$page->add_block(new Block("Random Image", $this->build_random_html($image), "left", 8));
 	}
 
-		public function build_random_html(Image $image, $query=null)
+	/**
-		{
+	 * @param Image $image
+	 * @param null|string $query
+	 * @return string
+	 */
+	public function build_random_html(Image $image, $query = null)
+	{
 
-			$i_id = int_escape($image->id);
+		$i_id = int_escape($image->id);
-			$h_view_link = make_link("post/view/$i_id", $query);
+		$h_view_link = make_link("post/view/$i_id", $query);
-			$h_thumb_link = $image->get_thumb_link();
+		$h_thumb_link = $image->get_thumb_link();
-			$h_tip = html_escape($image->get_tooltip());
+		$h_tip = html_escape($image->get_tooltip());
-			$tsize = get_thumbnail_size($image->width, $image->height);
+		$tsize = get_thumbnail_size($image->width, $image->height);
 
-			return "
+		return "
 				<center><div>
 
 					<a href='$h_view_link' style='position: relative; height: {$tsize[1]}px; width: {$tsize[0]}px;'>

ext/rotate/main.php

@@ -104,11 +104,15 @@ class RotateImage extends Extension {
 	
 	// Private functions
 	/* ----------------------------- */
-	
+
-	/*
+	/**
-		This function could be made much smaller by using the ImageReplaceEvent
+	 * This function could be made much smaller by using the ImageReplaceEvent
-		ie: Pretend that we are replacing the image with a rotated copy.
+	 * ie: Pretend that we are replacing the image with a rotated copy.
-	*/
+	 *
+	 * @param int $image_id
+	 * @param int $deg
+	 * @throws ImageRotateException
+	 */
 	private function rotate_image(/*int*/ $image_id, /*int*/ $deg) {
 		global $config, $user, $page, $database;
 		

ext/simpletest/main.php

@@ -88,19 +88,24 @@ define('ADMIN_NAME', "demo");
 define('ADMIN_PASS', "demo");
 
 /**
- * A set of common SCore activities to test
+ * Class SCoreWebTestCase
+ *
+ * A set of common SCore activities to test.
  */
 class SCoreWebTestCase extends WebTestCase {
 
- 	/**
+	/**
-	 * Click on a link or a button
+	 * Click on a link or a button.
+	 * @param string $text
+	 * @return string
 	 */
- 	public function click($text) {
+	public function click($text) {
 		return parent::click($text);
 	}
 
 	/**
-	 * Click the virtual browser's back button
+	 * Click the virtual browser's back button.
+	 * @return bool
 	 */
 	public function back() {
 		return parent::back();
@@ -165,9 +170,16 @@ class SCoreWebTestCase extends WebTestCase {
 }
 
 /**
- * A set of common Shimmie activities to test
+ * Class ShimmieWebTestCase
+ *
+ * A set of common Shimmie activities to test.
  */
 class ShimmieWebTestCase extends SCoreWebTestCase {
+	/**
+	 * @param string $filename
+	 * @param string|string[] $tags
+	 * @return int
+	 */
 	protected function post_image($filename, $tags) {
 		$image_id = -1;
 		$this->setMaximumRedirects(0);
@@ -195,6 +207,9 @@ class ShimmieWebTestCase extends SCoreWebTestCase {
 		return $image_id;
 	}
 
+	/**
+	 * @param int $image_id
+	 */
 	protected function delete_image($image_id) {
 		if($image_id > 0) {
 	        $this->get_page('post/view/'.$image_id);

ext/source_history/main.php

@@ -112,9 +112,10 @@ class Source_History extends Extension {
 			$config->set_int("ext_source_history_version", 3);
 		}
 	}
-	
+
-	/*
+	/**
-	 * this function is called when a revert request is received
+	 * This function is called when a revert request is received.
+	 * @param int $revert_id
 	 */
 	private function process_revert_request($revert_id) {
 		global $page;
@@ -201,7 +202,11 @@ class Source_History extends Extension {
 		// output results
 		$this->theme->display_revert_ip_results();
 	}
-	
+
+	/**
+	 * @param int $revert_id
+	 * @return mixed|null
+	 */
 	public function get_source_history_from_revert(/*int*/ $revert_id) {
 		global $database;
 		$row = $database->get_row("
@@ -212,6 +217,10 @@ class Source_History extends Extension {
 		return ($row ? $row : null);
 	}
 
+	/**
+	 * @param int $image_id
+	 * @return array
+	 */
 	public function get_source_history_from_id(/*int*/ $image_id) {
 		global $database;
 		$row = $database->get_all("
@@ -224,6 +233,10 @@ class Source_History extends Extension {
 		return ($row ? $row : array());
 	}
 
+	/**
+	 * @param int $page_id
+	 * @return array
+	 */
 	public function get_global_source_history($page_id) {
 		global $database;
 		$row = $database->get_all("
@@ -235,9 +248,13 @@ class Source_History extends Extension {
 		", array("offset" => ($page_id-1)*100));
 		return ($row ? $row : array());
 	}
-	
+
-	/*
+	/**
 	 * This function attempts to revert all changes by a given IP within an (optional) timeframe.
+	 *
+	 * @param string $name
+	 * @param string $ip
+	 * @param string $date
 	 */
 	public function process_revert_all_changes($name, $ip, $date) {
 		global $database;
@@ -331,9 +348,11 @@ class Source_History extends Extension {
 
 		log_info("source_history", 'Reverted '.count($result).' edits.');
 	}
-	
+
-	/*
+	/**
-	 * this function is called just before an images source is changed
+	 * This function is called just before an images source is changed.
+	 * @param Image $image
+	 * @param string $source
 	 */
 	private function add_source_history($image, $source) {
 		global $database, $config, $user;

ext/source_history/theme.php

@@ -2,6 +2,11 @@
 class Source_HistoryTheme extends Themelet {
 	var $messages = array();
 
+	/**
+	 * @param Page $page
+	 * @param int $image_id
+	 * @param array $history
+	 */
 	public function display_history_page(Page $page, /*int*/ $image_id, /*array*/ $history) {
 		global $user;
 		$start_string = "
@@ -45,6 +50,11 @@ class Source_HistoryTheme extends Themelet {
 		$page->add_block(new Block("Source History", $history_html, "main", 10));
 	}
 
+	/**
+	 * @param Page $page
+	 * @param array $history
+	 * @param int $page_number
+	 */
 	public function display_global_page(Page $page, /*array*/ $history, /*int*/ $page_number) {
 		$start_string = "
 			<div style='text-align: left'>
@@ -93,8 +103,9 @@ class Source_HistoryTheme extends Themelet {
 		$page->add_block(new Block("Navigation", $nav, "left"));
 	}
 
-	/*
+	/**
 	 * Add a section to the admin page.
+	 * @param string $validation_msg
 	 */
 	public function display_admin_block(/*string*/ $validation_msg='') {
 		global $page;
@@ -129,7 +140,11 @@ class Source_HistoryTheme extends Themelet {
 		$html = implode($this->messages, "\n");
 		$page->add_block(new Block("Bulk Revert Results", $html));
 	}
-	
+
+	/**
+	 * @param string $title
+	 * @param string $body
+	 */
 	public function add_status(/*string*/ $title, /*string*/ $body) {
 		$this->messages[] = '<p><b>'. $title .'</b><br>'. $body .'</p>';
 	}

ext/statsd/main.php

@@ -76,6 +76,9 @@ class StatsDInterface extends Extension {
 		StatsDInterface::$stats["shimmie.events.info-sets"] = "1|c";
 	}
 
+	/**
+	 * @return int
+	 */
 	public function get_priority() {return 99;}
 
 

ext/tag_edit/main.php

@@ -126,13 +126,17 @@ class LockSetEvent extends Event {
 class TagTermParseEvent extends Event {
 	var $term = null;
 	var $id = null;
-	var $metatag = false;
+	/** @var bool */
+	public $metatag = false;
 
 	public function __construct($term, $id) {
 		$this->term = $term;
 		$this->id = $id;
 	}
 
+	/**
+	 * @return bool
+	 */
 	public function is_metatag() {
 		return $this->metatag;
 	}
@@ -172,7 +176,11 @@ class TagEdit extends Extension {
 		global $user;
 		if($user->can("edit_image_owner")) {
 			$owner = User::by_name($_POST['tag_edit__owner']);
-			send_event(new OwnerSetEvent($event->image, $owner));
+			if ($owner instanceof User) {
+				send_event(new OwnerSetEvent($event->image, $owner));
+			} else {
+				throw new NullUserException("Error: No user with that name was found.");
+			}
 		}
 		if($this->can_tag($event->image) && isset($_POST['tag_edit__tags'])) {
 			send_event(new TagSetEvent($event->image, $_POST['tag_edit__tags']));
@@ -224,7 +232,10 @@ class TagEdit extends Extension {
 		$this->theme->display_mass_editor();
 	}
 
-	// When an alias is added, oldtag becomes inaccessable
+	/**
+	 * When an alias is added, oldtag becomes inaccessible.
+	 * @param AddAliasEvent $event
+	 */
 	public function onAddAlias(AddAliasEvent $event) {
 		$this->mass_tag_edit($event->oldtag, $event->newtag);
 	}
@@ -247,16 +258,28 @@ class TagEdit extends Extension {
 		if(!empty($matches)) $event->metatag = true;
 	}
 
+	/**
+	 * @param Image $image
+	 * @return bool
+	 */
 	private function can_tag(Image $image) {
 		global $user;
 		return ($user->can("edit_image_tag") || !$image->is_locked());
 	}
 
+	/**
+	 * @param Image $image
+	 * @return bool
+	 */
 	private function can_source(Image $image) {
 		global $user;
 		return ($user->can("edit_image_source") || !$image->is_locked());
 	}
 
+	/**
+	 * @param string $search
+	 * @param string $replace
+	 */
 	private function mass_tag_edit($search, $replace) {
 		global $database;
 
@@ -313,6 +336,10 @@ class TagEdit extends Extension {
 		}
 	}
 
+	/**
+	 * @param string|string[] $tags
+	 * @param string $source
+	 */
 	private function mass_source_edit($tags, $source) {
 		$tags = Tag::explode($tags);
 

ext/update/main.php

@@ -46,6 +46,9 @@ class Update extends Extension {
 		}
 	}
 
+	/**
+	 * @return bool
+	 */
 	private function download_shimmie() {
 		global $config;
 
@@ -70,6 +73,9 @@ class Update extends Extension {
 		return false;
 	}
 
+	/**
+	 * @return bool
+	 */
 	private function update_shimmie() {
 		global $config, $page;