From 4e9e5ca2bef72b7a40c147f2c57bebed76092785 Mon Sep 17 00:00:00 2001 From: jgen Date: Sat, 26 Apr 2014 05:01:49 -0400 Subject: [PATCH] Fixing/adding/cleaning up the PHP Doc comments. --- core/basethemelet.class.php | 51 +++++++++++++++++++++++++++--- core/block.class.php | 25 ++++++++++++--- core/event.class.php | 21 +++++++++++-- core/imageboard.pack.php | 30 +++++++++++++++--- core/user.class.php | 53 +++++++++++++++++++++++++++++--- core/userclass.class.php | 7 +++++ themes/futaba/themelet.class.php | 40 ++++++++++++++++++++++-- 7 files changed, 204 insertions(+), 23 deletions(-) diff --git a/core/basethemelet.class.php b/core/basethemelet.class.php index 49be4a419..3d62d3da0 100644 --- a/core/basethemelet.class.php +++ b/core/basethemelet.class.php @@ -1,10 +1,18 @@ add_block(new Block("Error", $message)); } - /** * A specific, common error message */ @@ -36,6 +43,9 @@ public function display_permission_denied() { /** * 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 @@ public function build_thumb_html(Image $image) { "\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 @@ public function display_paginator(Page $page, $base, $query, $page_number, $tota $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 ''.$name.''; } - + + /** + * @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 .= ""; @@ -87,7 +119,16 @@ private function gen_page_link_block($base_url, $query, $page, $current_page, $n if($page == $current_page) $paginator .= ""; 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; diff --git a/core/block.class.php b/core/block.class.php index 21b50dd18..bdbc215f4 100644 --- a/core/block.class.php +++ b/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 @@ public function __construct($header, $body, /*string*/ $section="main", /*int*/ $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; diff --git a/core/event.class.php b/core/event.class.php index 766a2c0f8..2b824e5bd 100644 --- a/core/event.class.php +++ b/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 @@ public function __construct($path) { * * 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 @@ public function page_matches(/*string*/ $name) { /** * 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 @@ public function count_args() { /* * Many things use these functions */ + + /** + * @return array + */ public function get_search_terms() { $search_terms = array(); if($this->count_args() === 2) { @@ -115,6 +124,10 @@ public function get_search_terms() { } return $search_terms; } + + /** + * @return int + */ public function get_page_number() { $page_number = 1; if($this->count_args() === 1) { @@ -126,6 +139,10 @@ public function get_page_number() { 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'); diff --git a/core/imageboard.pack.php b/core/imageboard.pack.php index 3c0d61c99..8c8e27b0a 100644 --- a/core/imageboard.pack.php +++ b/core/imageboard.pack.php @@ -152,6 +152,9 @@ public static function find_images(/*int*/ $start, /*int*/ $limit, $tags=array() /** * 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 @@ public static function count_images($tags=array()) { /** * 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 @@ public function get_owner() { } /** - * 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 @@ public function get_tag_array() { } /** - * 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 @@ public static function explode($tags, $tagme=true) { return $tag_array; } + /** + * @param $tags + * @return string + */ public static function implode($tags) { assert(is_string($tags) || is_array($tags)); @@ -1036,6 +1050,10 @@ public static function implode($tags) { return $tags; } + /** + * @param string $tag + * @return string + */ public static function resolve_alias($tag) { assert(is_string($tag)); @@ -1084,8 +1102,8 @@ public static function resolve_wildcard($tag) { /** * This function takes a list (array) of tags and changes any tags that have aliases * - * @param $tags Array of tags - * @return Array of tags + * @param array $tags 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; diff --git a/core/user.class.php b/core/user.class.php index 3117385ec..94e22c63c 100644 --- a/core/user.class.php +++ b/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 @@ public function __construct($row) { $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 @@ public static function by_session(/*string*/ $name, /*string*/ $session) { 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 @@ public static function by_id(/*int*/ $id) { 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 @@ public static function by_name(/*string*/ $name) { 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 @@ public static function by_name_and_hash(/*string*/ $name, /*string*/ $hash) { 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 @@ public static function by_list(/*int*/ $offset, /*int*/ $limit=50) { } - /* - * 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 @@ public function is_admin() { return ($this->class->name === "admin"); } + /** + * @param string $class + */ public function set_class(/*string*/ $class) { assert(is_string($class)); global $database; @@ -141,6 +183,9 @@ public function set_class(/*string*/ $class) { 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); diff --git a/core/userclass.class.php b/core/userclass.class.php index d960f9542..ee6871eaa 100644 --- a/core/userclass.class.php +++ b/core/userclass.class.php @@ -19,6 +19,13 @@ public function __construct($name, $parent=null, $abilities=array()) { $_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; diff --git a/themes/futaba/themelet.class.php b/themes/futaba/themelet.class.php index e79ff53c9..3f38fdfc8 100644 --- a/themes/futaba/themelet.class.php +++ b/themes/futaba/themelet.class.php @@ -1,7 +1,15 @@ 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 "[{$name}]"; } - + + /** + * @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 .= ""; @@ -21,7 +46,16 @@ public function futaba_gen_page_link_block($base_url, $query, $page, $current_pa if($page == $current_page) $paginator .= ""; 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;