More PHP Doc comments.

core/block.class.php

@@ -1,6 +1,9 @@
 <?php
+
 /**
- * A basic chunk of a page
+ * Class Block
+ *
+ * A basic chunk of a page.
  */
 class Block {
 	/**
@@ -79,9 +82,12 @@ class Block {
 
 
 /**
+ * Class NavBlock
+ *
  * A generic navigation block with a link to the main page.
  *
  * Used because "new NavBlock()" is easier than "new Block('Navigation', ..."
+ *
  */
 class NavBlock extends Block {
 	public function __construct() {

core/database.class.php

@@ -718,13 +718,51 @@ class MockDatabase extends Database {
 		return $this->responses[$this->query_id++];
 	}
 
+	/**
+	 * @param string $query
+	 * @param array $args
+	 * @return array|PDOStatement
+	 */
 	public function get_all($query, $args=array()) {return $this->execute($query, $args);}
+
+	/**
+	 * @param string $query
+	 * @param array $args
+	 * @return mixed|null|PDOStatement
+	 */
 	public function get_row($query, $args=array()) {return $this->execute($query, $args);}
+
+	/**
+	 * @param string $query
+	 * @param array $args
+	 * @return array|PDOStatement
+	 */
 	public function get_col($query, $args=array()) {return $this->execute($query, $args);}
+
+	/**
+	 * @param string $query
+	 * @param array $args
+	 * @return array|PDOStatement
+	 */
 	public function get_pairs($query, $args=array()) {return $this->execute($query, $args);}
+
+	/**
+	 * @param string $query
+	 * @param array $args
+	 * @return mixed|PDOStatement
+	 */
 	public function get_one($query, $args=array()) {return $this->execute($query, $args);}
+
+	/**
+	 * @param null|string $seq
+	 * @return int|string
+	 */
 	public function get_last_insert_id($seq) {return $this->query_id;}
 
+	/**
+	 * @param string $sql
+	 * @return string
+	 */
 	public function scoreql_to_sql($sql) {return $sql;}
 	public function create_table($name, $def) {}
 	public function connect_engine() {}

core/email.class.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * Class Email
+ *
  * A generic email.
  */
 class Email {

core/event.class.php

@@ -301,6 +301,8 @@ class LogEvent extends Event {
 
 	/**
 	 * Extra data to be held separate
+	 *
+	 * @var array
 	 */
 	public $args;
 
@@ -308,7 +310,7 @@ class LogEvent extends Event {
 	 * @param string $section
 	 * @param int $priority
 	 * @param string $message
-	 * @param $args
+	 * @param array $args
 	 */
 	public function __construct($section, $priority, $message, $args) {
 		$this->section = $section;

core/exceptions.class.php

@@ -1,11 +1,16 @@
 <?php
+
 /**
- * A base exception to be caught by the upper levels
+ * Class SCoreException
+ *
+ * A base exception to be caught by the upper levels.
  */
 class SCoreException extends Exception {}
 
 /**
- * A fairly common, generic exception
+ * Class PermissionDeniedException
+ *
+ * A fairly common, generic exception.
  */
 class PermissionDeniedException extends SCoreException {}
 

core/extension.class.php

@@ -70,6 +70,8 @@
  */
 
 /**
+ * Class Extension
+ *
  * send_event(BlahEvent()) -> onBlah($event)
  *
  * Also loads the theme object into $this->theme if available
@@ -128,7 +130,9 @@ abstract class Extension {
 }
 
 /**
- * Several extensions have this in common, make a common API
+ * Class FormatterExtension
+ *
+ * Several extensions have this in common, make a common API.
  */
 abstract class FormatterExtension extends Extension {
 	/**
@@ -153,8 +157,10 @@ abstract class FormatterExtension extends Extension {
 }
 
 /**
+ * Class DataHandlerExtension
+ *
  * This too is a common class of extension with many methods in common,
- * so we have a base class to extend from
+ * so we have a base class to extend from.
  */
 abstract class DataHandlerExtension extends Extension {
 	/**

core/imageboard.pack.php

@@ -31,6 +31,8 @@ $order_sql = null; // this feels ugly
 require_once "lib/flexihash.php";
 
 /**
+ * Class Image
+ *
  * An object representing an entry in the images table.
  *
  * As of 2.2, this no longer necessarily represents an
@@ -1017,9 +1019,12 @@ class Image {
 }
 
 /**
+ * Class Tag
+ *
  * A class for organising the tag related functions.
  *
  * All the methods are static, one should never actually use a tag object.
+ *
  */
 class Tag {
 	/**

core/page.class.php

@@ -28,10 +28,12 @@
 
 
 /**
+ * Class Page
+ *
  * A data structure for holding all the bits of data that make up a page.
  *
  * The various extensions all add whatever they want to this structure,
- * then Layout turns it into HTML
+ * then Layout turns it into HTML.
  */
 class Page {
 	/** @name Overall */

core/user.class.php

@@ -6,9 +6,11 @@ function _new_user($row) {
 
 
 /**
+ * Class User
+ *
  * An object representing a row in the "users" table.
  *
- * The currently logged in user will always be accessible via the global variable $user
+ * The currently logged in user will always be accessible via the global variable $user.
  */
 class User {
 	/** @var int */

core/userclass.class.php

@@ -4,6 +4,9 @@
  */
 $_user_classes = array();
 
+/**
+ * Class UserClass
+ */
 class UserClass {
 
 	/**

ext/user/theme.php

@@ -110,6 +110,11 @@ class UserPageTheme extends Themelet {
 		$page->add_block(new Block("Login", $html, "left", 90));
 	}
 
+	/**
+	 * @param Page $page
+	 * @param array $uploads
+	 * @param array $comments
+	 */
 	public function display_ip_list(Page $page, $uploads, $comments) {
 		$html = "<table id='ip-history'>";
 		$html .= "<tr><td>Uploaded from: ";

themes/danbooru/comment.theme.php

@@ -1,6 +1,12 @@
 <?php
 
 class CustomCommentListTheme extends CommentListTheme {
+	/**
+	 * @param array $images
+	 * @param int $page_number
+	 * @param int $total_pages
+	 * @param bool $can_post
+	 */
 	public function display_comment_list($images, $page_number, $total_pages, $can_post) {
 		global $config, $page, $user;
 
@@ -86,7 +92,11 @@ class CustomCommentListTheme extends CommentListTheme {
 		// no recent comments in this theme
 	}
 
-
+	/**
+	 * @param Comment $comment
+	 * @param bool $trim
+	 * @return string
+	 */
 	protected function comment_to_html($comment, $trim=false) {
 		global $user;
 

themes/danbooru/custompage.class.php

@@ -1,7 +1,9 @@
 <?php
 
 class CustomPage extends Page {
-	var $left_enabled = true;
+	/** @var bool */
+	public $left_enabled = true;
+
 	public function disable_left() {
 		$this->left_enabled = false;
 	}

themes/danbooru/index.theme.php

@@ -1,6 +1,10 @@
 <?php
 
 class CustomIndexTheme extends IndexTheme {
+	/**
+	 * @param Page $page
+	 * @param null|array $images
+	 */
 	public function display_page(Page $page, $images) {
 		global $config;
 
@@ -33,7 +37,12 @@ class CustomIndexTheme extends IndexTheme {
 		}
 	}
 
-
+	/**
+	 * @param int $page_number
+	 * @param int $total_pages
+	 * @param array $search_terms
+	 * @return string
+	 */
 	protected function build_navigation($page_number, $total_pages, $search_terms) {
 		$h_search_string = count($search_terms) == 0 ? "" : html_escape(implode(" ", $search_terms));
 		$h_search_link = make_link();
@@ -48,6 +57,11 @@ class CustomIndexTheme extends IndexTheme {
 		return $h_search;
 	}
 
+	/**
+	 * @param Image[] $images
+	 * @param string $query
+	 * @return string
+	 */
 	protected function build_table($images, $query) {
 		$h_query = html_escape($query);
 		$table = "<div class='shm-image-list' data-query='$h_query'>";

themes/danbooru/themelet.class.php

@@ -1,23 +1,52 @@
 <?php
 class Themelet extends BaseThemelet {
+	/**
+	 * @param Page $page
+	 * @param string $base
+	 * @param string $query
+	 * @param int $page_number
+	 * @param int $total_pages
+	 */
 	public function display_paginator(Page $page, $base, $query, $page_number, $total_pages) {
 		if($total_pages == 0) $total_pages = 1;
 		$body = $this->build_paginator($page_number, $total_pages, $base, $query);
 		$page->add_block(new Block(null, $body, "main", 90));
 	}
 
+	/**
+	 * @param string $base_url
+	 * @param string $query
+	 * @param int|string $page
+	 * @param string $name
+	 * @return string
+	 */
 	private function gen_page_link($base_url, $query, $page, $name) {
 		$link = make_link("$base_url/$page", $query);
 	    return "<a href='$link'>$name</a>";
 	}
-	
+
+	/**
+	 * @param string $base_url
+	 * @param string $query
+	 * @param int|string $page
+	 * @param int|string $current_page
+	 * @param string $name
+	 * @return string
+	 */
 	private function gen_page_link_block($base_url, $query, $page, $current_page, $name) {
 		$paginator = "";
 	    if($page == $current_page) $paginator .= "<b>$page</b>";
 	    else $paginator .= $this->gen_page_link($base_url, $query, $page, $name);
 	    return $paginator;
 	}
-					
+
+	/**
+	 * @param int $current_page
+	 * @param int $total_pages
+	 * @param string $base_url
+	 * @param string $query
+	 * @return string
+	 */
 	private function build_paginator($current_page, $total_pages, $base_url, $query) {
 		$next = $current_page + 1;
 		$prev = $current_page - 1;

themes/danbooru/user.theme.php

@@ -76,6 +76,11 @@ class CustomUserPageTheme extends UserPageTheme {
 		$page->add_block(new Block("Signup", $html));
 	}
 
+	/**
+	 * @param Page $page
+	 * @param array $uploads
+	 * @param array $comments
+	 */
 	public function display_ip_list(Page $page, $uploads, $comments) {
 		$html = "<table id='ip-history' style='width: 400px;'>";
 		$html .= "<tr><td>Uploaded from: ";

themes/danbooru2/ext_manager.theme.php

@@ -1,10 +1,20 @@
 <?php
 
 class CustomExtManagerTheme extends ExtManagerTheme {
+	/**
+	 * @param Page $page
+	 * @param array $extensions
+	 * @param bool $editable
+	 */
 	public function display_table(Page $page, /*array*/ $extensions, /*bool*/ $editable) {
 		$page->disable_left();
 		parent::display_table($page, $extensions, $editable);
 	}
+
+	/**
+	 * @param Page $page
+	 * @param ExtensionInfo $info
+	 */
 	public function display_doc(Page $page, ExtensionInfo $info) {
 		$page->disable_left();
 		parent::display_doc($page, $info);

themes/danbooru2/themelet.class.php

@@ -1,23 +1,52 @@
 <?php
 class Themelet extends BaseThemelet {
+	/**
+	 * @param Page $page
+	 * @param string $base
+	 * @param string $query
+	 * @param int $page_number
+	 * @param int $total_pages
+	 */
 	public function display_paginator(Page $page, $base, $query, $page_number, $total_pages) {
 		if($total_pages == 0) $total_pages = 1;
 		$body = $this->build_paginator($page_number, $total_pages, $base, $query);
 		$page->add_block(new Block(null, $body, "main", 90));
 	}
 
+	/**
+	 * @param string $base_url
+	 * @param string $query
+	 * @param int|string $page
+	 * @param string $name
+	 * @return string
+	 */
 	private function gen_page_link($base_url, $query, $page, $name) {
 		$link = make_link("$base_url/$page", $query);
 	    return "<a href='$link'>$name</a>";
 	}
-	
+
+	/**
+	 * @param string $base_url
+	 * @param string $query
+	 * @param int|string $page
+	 * @param int|string $current_page
+	 * @param string $name
+	 * @return string
+	 */
 	private function gen_page_link_block($base_url, $query, $page, $current_page, $name) {
 		$paginator = "";
 	    if($page == $current_page) $paginator .= "<b>$page</b>";
 	    else $paginator .= $this->gen_page_link($base_url, $query, $page, $name);
 	    return $paginator;
 	}
-					
+
+	/**
+	 * @param int $current_page
+	 * @param int $total_pages
+	 * @param string $base_url
+	 * @param string $query
+	 * @return string
+	 */
 	private function build_paginator($current_page, $total_pages, $base_url, $query) {
 		$next = $current_page + 1;
 		$prev = $current_page - 1;

themes/danbooru2/user.theme.php

@@ -76,6 +76,11 @@ class CustomUserPageTheme extends UserPageTheme {
 		$page->add_block(new Block("Signup", $html));
 	}
 
+	/**
+	 * @param Page $page
+	 * @param array $uploads
+	 * @param array $comments
+	 */
 	public function display_ip_list(Page $page, $uploads, $comments) {
 		$html = "<table id='ip-history' style='width: 400px;'>";
 		$html .= "<tr><td>Uploaded from: ";

themes/danbooru2/view.theme.php

@@ -1,6 +1,10 @@
 <?php
 
 class CustomViewImageTheme extends ViewImageTheme {
+	/**
+	 * @param Image $image
+	 * @param $editor_parts
+	 */
 	public function display_page(Image $image, $editor_parts) {
 		global $page;
 		$page->set_title("Image {$image->id}: ".html_escape($image->get_tag_list()));
@@ -9,7 +13,11 @@ class CustomViewImageTheme extends ViewImageTheme {
 		$page->add_block(new Block("Information", $this->build_information($image), "left", 15));
 		$page->add_block(new Block(null, $this->build_info($image, $editor_parts), "main", 15));
 	}
-	
+
+	/**
+	 * @param Image $image
+	 * @return string
+	 */
 	private function build_information(Image $image) {
 		$h_owner = html_escape($image->get_owner()->name);
 		$h_ownerlink = "<a href='".make_link("user/$h_owner")."'>$h_owner</a>";
@@ -50,6 +58,10 @@ class CustomViewImageTheme extends ViewImageTheme {
 		return $html;
 	}
 
+	/**
+	 * @param Image $image
+	 * @return string
+	 */
 	protected function build_navigation(Image $image) {
 		//$h_pin = $this->build_pin($image);
 		$h_search = "

themes/lite/layout.class.php

@@ -10,7 +10,9 @@
 class Layout {
 
 	/**
-	 * turns the Page into HTML
+	 * turns the Page into HTML.
+	 *
+	 * @param Page $page
 	 */
 	public function display_page(Page $page) {
 		global $config, $user;
@@ -210,9 +212,14 @@ EOD;
 
 
 	/**
-	 * A handy function which does exactly what it says in the method name
+	 * A handy function which does exactly what it says in the method name.
+	 *
+	 * @param Block $block
+	 * @param bool $hidable
+	 * @param string $salt
+	 * @return string
 	 */
-	public function block_to_html($block, $hidable=false, $salt="") {
+	public function block_to_html(Block $block, $hidable=false, $salt="") {
 		$h = $block->header;
 		$b = $block->body;
 		$i = str_replace(' ', '_', $h) . $salt;
@@ -238,6 +245,12 @@ EOD;
 		return $html;
 	}
 
+	/**
+	 * @param string $link
+	 * @param null|string $desc
+	 * @param array $pages_matched
+	 * @return null|string
+	 */
 	public function navlinks($link, $desc, $pages_matched) {
 		/**
 		 * Woo! We can actually SEE THE CURRENT PAGE!! (well... see it highlighted in the menu.)

themes/lite/user.theme.php

@@ -74,6 +74,11 @@ class CustomUserPageTheme extends UserPageTheme {
 		$page->add_block(new Block("Signup", $html));
 	}
 
+	/**
+	 * @param Page $page
+	 * @param array $uploads
+	 * @param array $comments
+	 */
 	public function display_ip_list(Page $page, $uploads, $comments) {
 		$html = "<table id='ip-history' style='width: 400px;'>";
 		$html .= "<tr><td>Uploaded from: ";