Fixing/adding/cleaning up the PHP Doc comments.
This commit is contained in:
jgen
parent
a8dd045586
commit
4e9e5ca2be
7 changed files with 204 additions and 23 deletions
|
|
@ -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>";
|
||||
|
|
@ -87,7 +119,16 @@ class BaseThemelet {
|
|||
if($page == $current_page) $paginator .= "</b>";
|
||||
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;
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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');
|
||||
|
|
|
|||
|
|
@ -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
|
||||
* @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;
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
|
|
|
|||
|
|
@ -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>";
|
||||
|
|
@ -21,7 +46,16 @@ class Themelet extends BaseThemelet {
|
|||
if($page == $current_page) $paginator .= "</b>";
|
||||
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;
|
||||
|
|
|
|||
Reference in a new issue