Fixing/adding/cleaning up the PHP Doc comments.

core/basethemelet.class.php

@@ -1,10 +1,18 @@
 <?php
+
 /**
+ * Class BaseThemelet
+ *
  * A collection of common functions for theme parts
  */
 class BaseThemelet {
+
 	/**
 	 * Generic error message display
+	 *
+	 * @param int $code
+	 * @param string $title
+	 * @param string $message
 	 */
 	public function display_error(/*int*/ $code, /*string*/ $title, /*string*/ $message) {
 		global $page;
@@ -24,7 +32,6 @@ class BaseThemelet {
 		$page->add_block(new Block("Error", $message));
 	}
 
-
 	/**
 	 * A specific, common error message
 	 */
@@ -36,6 +43,9 @@ class BaseThemelet {
 	/**
 	 * Generic thumbnail code; returns HTML rather than adding
 	 * a block since thumbs tend to go inside blocks...
+	 *
+	 * @param Image $image
+	 * @return string
 	 */
 	public function build_thumb_html(Image $image) {
 		global $config;
@@ -65,9 +75,14 @@ class BaseThemelet {
 				"</a>\n";
 	}
 
-
 	/**
-	 * Add a generic paginator
+	 * Add a generic paginator.
+	 *
+	 * @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;
@@ -75,11 +90,28 @@ class BaseThemelet {
 		$page->add_block(new Block(null, $body, "main", 90, "paginator"));
 	}
 
+	/**
+	 * Generate a single HTML link.
+	 *
+	 * @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>";
@@ -88,6 +120,15 @@ class BaseThemelet {
 	    return $paginator;
 	}
 
+	/**
+	 * Build the 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;

core/block.class.php

@@ -6,14 +6,14 @@ class Block {
 	/**
 	 * The block's title
 	 *
-	 * @retval string
+	 * @var string
 	 */
 	public $header;
 
 	/**
 	 * The content
 	 *
-	 * @retval string
+	 * @var string
 	 */
 	public $body;
 
@@ -21,7 +21,7 @@ class Block {
 	 * Where the block should be placed. The default theme supports
 	 * "main" and "left", other themes can add their own areas
 	 *
-	 * @retval string
+	 * @var string
 	 */
 	public $section;
 
@@ -30,15 +30,24 @@ class Block {
 	 * numbers appear lower. The scale is 0-100 by convention,
 	 * though any number or string will work.
 	 *
-	 * @retval int
+	 * @var int
 	 */
 	public $position;
 
 	/**
-	 *
+	 * @var int
 	 */
 	public $id;
 
+	/**
+	 * Construct a block.
+	 *
+	 * @param string $header
+	 * @param string $body
+	 * @param string $section
+	 * @param int $position
+	 * @param null|int $id
+	 */
 	public function __construct($header, $body, /*string*/ $section="main", /*int*/ $position=50, $id=null) {
 		$this->header = $header;
 		$this->body = $body;
@@ -47,6 +56,12 @@ class Block {
 		$this->id = str_replace(' ', '_', is_null($id) ? (is_null($header) ? md5($body) : $header) . $section : $id);
 	}
 
+	/**
+	 * Get the HTML for this block.
+	 *
+	 * @param bool $hidable
+	 * @return string
+	 */
 	public function get_html($hidable=false) {
 		$h = $this->header;
 		$b = $this->body;

core/event.class.php

@@ -30,6 +30,9 @@ class PageRequestEvent extends Event {
 	public $arg_count;
 	public $part_count;
 
+	/**
+	 * @param string $path
+	 */
 	public function __construct($path) {
 		global $config;
 
@@ -63,6 +66,7 @@ class PageRequestEvent extends Event {
 	 *
 	 * If it matches, store the remaining path elements in $args
 	 *
+	 * @param string $name
 	 * @return bool
 	 */
 	public function page_matches(/*string*/ $name) {
@@ -84,8 +88,9 @@ class PageRequestEvent extends Event {
 
 	/**
 	 * Get the n th argument of the page request (if it exists.)
-	 * @param $n integer
+	 *
-	 * @return The argmuent (string) or NULL
+	 * @param int $n
+	 * @return string|null The argmuent (string) or NULL
 	 */
 	public function get_arg(/*int*/ $n) {
 		$offset = $this->part_count + $n;
@@ -108,6 +113,10 @@ class PageRequestEvent extends Event {
 	/*
 	 * Many things use these functions
 	 */
+
+	/**
+	 * @return array
+	 */
 	public function get_search_terms() {
 		$search_terms = array();
 		if($this->count_args() === 2) {
@@ -115,6 +124,10 @@ class PageRequestEvent extends Event {
 		}
 		return $search_terms;
 	}
+
+	/**
+	 * @return int
+	 */
 	public function get_page_number() {
 		$page_number = 1;
 		if($this->count_args() === 1) {
@@ -126,6 +139,10 @@ class PageRequestEvent extends Event {
 		if($page_number === 0) $page_number = 1; // invalid -> 0
 		return $page_number;
 	}
+
+	/**
+	 * @return int
+	 */
 	public function get_page_size() {
 		global $config;
 		return $config->get_int('index_images');

core/imageboard.pack.php

@@ -152,6 +152,9 @@ class Image {
 
 	/**
 	 * Count the number of image results for a given search
+	 *
+	 * @param array $tags
+	 * @return mixed
 	 */
 	public static function count_images($tags=array()) {
 		assert(is_array($tags));
@@ -181,6 +184,9 @@ class Image {
 
 	/**
 	 * Count the number of pages for a given search
+	 *
+	 * @param array $tags
+	 * @return float
 	 */
 	public static function count_pages($tags=array()) {
 		assert(is_array($tags));
@@ -250,7 +256,9 @@ class Image {
 	}
 
 	/**
-	 * Set the image's owner
+	 * Set the image's owner.
+	 *
+	 * @param User $owner
 	 */
 	public function set_owner(User $owner) {
 		global $database;
@@ -272,7 +280,9 @@ class Image {
 	}
 
 	/**
-	 * Get this image's tags as a string
+	 * Get this image's tags as a string.
+	 *
+	 * @return string
 	 */
 	public function get_tag_list() {
 		return Tag::implode($this->get_tag_array());
@@ -1022,6 +1032,10 @@ class Tag {
 		return $tag_array;
 	}
 
+	/**
+	 * @param $tags
+	 * @return string
+	 */
 	public static function implode($tags) {
 		assert(is_string($tags) || is_array($tags));
 
@@ -1036,6 +1050,10 @@ class Tag {
 		return $tags;
 	}
 
+	/**
+	 * @param string $tag
+	 * @return string
+	 */
 	public static function resolve_alias($tag) {
 		assert(is_string($tag));
 
@@ -1084,8 +1102,8 @@ class Tag {
 	/**
 	 * This function takes a list (array) of tags and changes any tags that have aliases
 	 *
-	 * @param $tags Array of tags
+	 * @param array $tags Array of tags
-	 * @return Array of tags
+	 * @return array of tags
 	 */
 	public static function resolve_aliases($tags) {
 		assert(is_array($tags));
@@ -1135,6 +1153,10 @@ function move_upload_to_archive(DataUploadEvent $event) {
 /**
  * Given a full size pair of dimensions, return a pair scaled down to fit
  * into the configured thumbnail square, with ratio intact
+ *
+ * @param int $orig_width
+ * @param int $orig_height
+ * @return array
  */
 function get_thumbnail_size(/*int*/ $orig_width, /*int*/ $orig_height) {
 	global $config;

core/user.class.php

@@ -8,16 +8,23 @@ function _new_user($row) {
 /**
  * An object representing a row in the "users" table.
  *
- * The currently logged in user will always be accessable via the global variable $user
+ * The currently logged in user will always be accessible via the global variable $user
  */
 class User {
+	/** @var int */
 	public $id;
+
+	/** @var string */
 	public $name;
+
+	/** @var string */
 	public $email;
+
 	public $join_date;
+
 	public $passhash;
 
-	/* @var UserClass */
+	/** @var UserClass */
 	var $class;
 
 	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
@@ -44,6 +51,13 @@ class User {
 		$this->class = $_user_classes[$row["class"]];
 	}
 
+	/**
+	 * Construct a User by session.
+	 *
+	 * @param string $name
+	 * @param string $session
+	 * @return null|User
+	 */
 	public static function by_session(/*string*/ $name, /*string*/ $session) {
 		global $config, $database;
 		$row = $database->cache->get("user-session-$name-$session");
@@ -60,6 +74,11 @@ class User {
 		return is_null($row) ? null : new User($row);
 	}
 
+	/**
+	 * Construct a User by session.
+	 * @param int $id
+	 * @return null|User
+	 */
 	public static function by_id(/*int*/ $id) {
 		assert(is_numeric($id));
 		global $database;
@@ -72,6 +91,11 @@ class User {
 		return is_null($row) ? null : new User($row);
 	}
 
+	/**
+	 * Construct a User by name.
+	 * @param string $name
+	 * @return null|User
+	 */
 	public static function by_name(/*string*/ $name) {
 		assert(is_string($name));
 		global $database;
@@ -79,6 +103,12 @@ class User {
 		return is_null($row) ? null : new User($row);
 	}
 
+	/**
+	 * Construct a User by name and hash.
+	 * @param string $name
+	 * @param string $hash
+	 * @return null|User
+	 */
 	public static function by_name_and_hash(/*string*/ $name, /*string*/ $hash) {
 		assert(is_string($name));
 		assert(is_string($hash));
@@ -88,6 +118,11 @@ class User {
 		return is_null($row) ? null : new User($row);
 	}
 
+	/**
+	 * @param int $offset
+	 * @param int $limit
+	 * @return array
+	 */
 	public static function by_list(/*int*/ $offset, /*int*/ $limit=50) {
 		assert(is_numeric($offset));
 		assert(is_numeric($limit));
@@ -97,8 +132,12 @@ class User {
 	}
 
 
-	/*
+	/* useful user object functions start here */
-	 * useful user object functions start here
+
+
+	/**
+	 * @param string $ability
+	 * @return bool
 	 */
 	public function can($ability) {
 		return $this->class->can($ability);
@@ -134,6 +173,9 @@ class User {
 		return ($this->class->name === "admin");
 	}
 
+	/**
+	 * @param string $class
+	 */
 	public function set_class(/*string*/ $class) {
 		assert(is_string($class));
 		global $database;
@@ -141,6 +183,9 @@ class User {
 		log_info("core-user", 'Set class for '.$this->name.' to '.$class);
 	}
 
+	/**
+	 * @param string $password
+	 */
 	public function set_password(/*string*/ $password) {
 		global $database;
 		$hash = md5(strtolower($this->name) . $password);

core/userclass.class.php

@@ -19,6 +19,13 @@ class UserClass {
 		$_user_classes[$name] = $this;
 	}
 
+	/**
+	 * Determine if this class of user can perform an action or has ability.
+	 *
+	 * @param string $ability
+	 * @return bool
+	 * @throws SCoreException
+	 */
 	public function can(/*string*/ $ability) {
 		global $config;
 

themes/futaba/themelet.class.php

@@ -1,7 +1,15 @@
 <?php
 class Themelet extends BaseThemelet {
+
 	/**
-	 * Add a generic paginator
+	 * Add a generic paginator.
+	 *
+	 * @param Page $page
+	 * @param string $base
+	 * @param string $query
+	 * @param int $page_number
+	 * @param int $total_pages
+	 * @param int $position
 	 */
 	public function display_paginator(Page $page, $base, $query, $page_number, $total_pages, $position=90) {
 		if($total_pages == 0) $total_pages = 1;
@@ -9,11 +17,28 @@ class Themelet extends BaseThemelet {
 		$page->add_block(new Block(null, $body, "main", $position));
 	}
 
+	/**
+	 * Generate a single HTML link.
+	 *
+	 * @param string $base_url
+	 * @param string $query
+	 * @param int|string $page
+	 * @param string $name
+	 * @return string
+	 */
 	public function futaba_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
+	 */
 	public function futaba_gen_page_link_block($base_url, $query, $page, $current_page, $name) {
 		$paginator = "";
 	    if($page == $current_page) $paginator .= "<b>";
@@ -22,6 +47,15 @@ class Themelet extends BaseThemelet {
 	    return $paginator;
 	}
 
+	/**
+	 * Build the paginator.
+	 *
+	 * @param int $current_page
+	 * @param int $total_pages
+	 * @param string $base_url
+	 * @param string $query
+	 * @return string
+	 */
 	public function futaba_build_paginator($current_page, $total_pages, $base_url, $query) {
 		$next = $current_page + 1;
 		$prev = $current_page - 1;