From 5af54bb9e091d2a6166f30044e6e370a6c792920 Mon Sep 17 00:00:00 2001 From: "green-ponies (jgen)" Date: Tue, 7 Feb 2012 20:05:38 -0500 Subject: [PATCH 1/4] Added some more comments and type hints. --- core/imageboard.pack.php | 11 ++++++++--- core/user.class.php | 3 +++ core/util.inc.php | 29 +++++++++++++++++++++++++++-- 3 files changed, 38 insertions(+), 5 deletions(-) diff --git a/core/imageboard.pack.php b/core/imageboard.pack.php index ca198452..084cd712 100644 --- a/core/imageboard.pack.php +++ b/core/imageboard.pack.php @@ -106,8 +106,10 @@ class Image { /** * Search for an array of images + * + * @retval Array */ - public static function find_images($start, $limit, $tags=array()) { + public static function find_images(/*int*/ $start, /*int*/ $limit, $tags=array()) { assert(is_numeric($start)); assert(is_numeric($limit)); assert(is_array($tags)); @@ -383,7 +385,7 @@ class Image { /** * Set the image's source URL */ - public function set_source($source) { + public function set_source(/*string*/ $source) { global $database; if(empty($source)) $source = null; if($source != $this->source) { @@ -392,7 +394,10 @@ class Image { } } - + /** + * Check if the image is locked. + * @retval bool + */ public function is_locked() { return ($this->locked === true || $this->locked == "Y" || $this->locked == "t"); } diff --git a/core/user.class.php b/core/user.class.php index 0c98597b..843d6c9d 100644 --- a/core/user.class.php +++ b/core/user.class.php @@ -216,6 +216,7 @@ class User { /** * Get a snippet of HTML which will render the user's avatar, be that * a local file, a remote file, a gravatar, a something else, etc + * @retval String of HTML */ public function get_avatar_html() { // FIXME: configurable @@ -242,6 +243,8 @@ class User { * authtok = md5(sesskey, salt), presented to the user in web forms, to make sure that * the form was generated within the session. Salted and re-hashed so that * reading a web page from the user's cache doesn't give access to the session key + * + * @retval String containing auth token (MD5sum) */ public function get_auth_token() { global $config; diff --git a/core/util.inc.php b/core/util.inc.php index 3529fb87..8ddb2fb3 100644 --- a/core/util.inc.php +++ b/core/util.inc.php @@ -190,12 +190,26 @@ function undb_bool($val) { if($val === false || $val == 'N' || $val == 'n' || $val == 'F' || $val == 'f' || $val === 0) return false; } -function startsWith($haystack, $needle) { +/** + * Checks if a given string contains another at the beginning. + * + * @param $haystack String to examine. + * @param $needle String to look for. + * @retval bool + */ +function startsWith(/*string*/ $haystack, /*string*/ $needle) { $length = strlen($needle); return (substr($haystack, 0, $length) === $needle); } -function endsWith($haystack, $needle) { +/** + * Checks if a given string contains another at the end. + * + * @param $haystack String to examine. + * @param $needle String to look for. + * @retval bool + */ +function endsWith(/*string*/ $haystack, /*string*/ $needle) { $length = strlen($needle); $start = $length * -1; //negative return (substr($haystack, $start) === $needle); @@ -621,6 +635,7 @@ function log_msg($section, $priority, $message) { send_event(new LogEvent($section, $priority, $message)); } +// More shorthand ways of logging function log_debug($section, $message) {log_msg($section, SCORE_LOG_DEBUG, $message);} function log_info($section, $message) {log_msg($section, SCORE_LOG_INFO, $message);} function log_warning($section, $message) {log_msg($section, SCORE_LOG_WARNING, $message);} @@ -847,6 +862,13 @@ function send_event(Event $event) { // string representation of a number, it's two numbers separated by a space. // What the fuck were the PHP developers smoking. $_load_start = microtime(true); + +/** + * Collects some debug information (execution time, memory usage, queries, etc) + * and formats it to stick in the footer of the page. + * + * @retval String of debug info to add to the page. + */ function get_debug_info() { global $config, $_event_count, $database, $_execs, $_load_start; @@ -1051,6 +1073,9 @@ function _load_extensions() { ctx_log_endok(); } +/** + * Used to display fatal errors to the web user. + */ function _fatal_error(Exception $e) { $version = VERSION; $message = $e->getMessage(); From ac1b3d00e296da55b944f94c6a9dc305a1b34ba0 Mon Sep 17 00:00:00 2001 From: "green-ponies (jgen)" Date: Tue, 7 Feb 2012 20:13:58 -0500 Subject: [PATCH 2/4] Some more comments. --- core/event.class.php | 11 +++++++++++ core/page.class.php | 2 +- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/core/event.class.php b/core/event.class.php index cbff2fcf..e6511cff 100644 --- a/core/event.class.php +++ b/core/event.class.php @@ -39,6 +39,8 @@ class PageRequestEvent extends Event { * Test if the requested path matches a given pattern. * * If it matches, store the remaining path elements in $args + * + * @retval bool */ public function page_matches(/*string*/ $name) { $parts = explode("/", $name); @@ -57,6 +59,11 @@ class PageRequestEvent extends Event { return true; } + /** + * Get the n th argument of the page request (if it exists.) + * @param $n integer + * @retval The argmuent (string) or NULL + */ public function get_arg(/*int*/ $n) { $offset = $this->part_count + $n; if($offset >= 0 && $offset < $this->arg_count) { @@ -67,6 +74,10 @@ class PageRequestEvent extends Event { } } + /** + * Returns the number of arguments the page request has. + * @retval int + */ public function count_args() { return (int)($this->arg_count - $this->part_count); } diff --git a/core/page.class.php b/core/page.class.php index 4060d4f7..e3102ccc 100644 --- a/core/page.class.php +++ b/core/page.class.php @@ -237,7 +237,7 @@ class Page { protected function add_auto_html_headers() { $data_href = get_base_href(); - $this->add_html_header(""); + $this->add_html_header(""); /* Attempt to cache the CSS & JavaScript files */ if ($this->add_cached_auto_html_headers() === FALSE) { From 0cdc3033979021f03c9dd41b62138b1305ef46c8 Mon Sep 17 00:00:00 2001 From: "green-ponies (jgen)" Date: Tue, 7 Feb 2012 20:25:05 -0500 Subject: [PATCH 3/4] Just more comments. --- ext/upload/main.php | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/ext/upload/main.php b/ext/upload/main.php index 938a27fa..571a56af 100644 --- a/ext/upload/main.php +++ b/ext/upload/main.php @@ -1,5 +1,5 @@ get_bool("upload_anon") || !$user->is_anonymous()); } - // Helper function based on the one from the online PHP Documentation - // which is licensed under Creative Commons Attribution 3.0 License - // TODO: Make these messages user/admin editable + /** + * Returns a descriptive error message for the specified PHP error code. + * + * This is a helper function based on the one from the online PHP Documentation + * which is licensed under Creative Commons Attribution 3.0 License + * + * TODO: Make these messages user/admin editable + * + * @param $error_code PHP error code (int) + * @retval String + */ private function upload_error_message($error_code) { switch ($error_code) { case UPLOAD_ERR_INI_SIZE: @@ -247,6 +261,10 @@ class Upload extends SimpleExtension { } } + /** + * Handle an upload. + * @retval bool TRUE on upload successful. + */ private function try_upload($file, $tags, $source, $replace='') { global $page; global $config; @@ -293,6 +311,10 @@ class Upload extends SimpleExtension { return $ok; } + /** + * Handle an transload. + * @retval bool TRUE on transload successful. + */ private function try_transload($url, $tags, $source, $replace='') { global $page; global $config; From 2d443f0be9c3fef126886a9f3df8081226cfc8b1 Mon Sep 17 00:00:00 2001 From: "green-ponies (jgen)" Date: Tue, 7 Feb 2012 21:52:11 -0500 Subject: [PATCH 4/4] Mostly just adding the Link to comments. --- contrib/ban_words/main.php | 1 + contrib/bulk_add/main.php | 5 ++++- contrib/et/main.php | 3 +++ contrib/featured/main.php | 1 + contrib/handle_flash/main.php | 3 ++- contrib/handle_svg/main.php | 3 ++- contrib/ipban/main.php | 1 + contrib/log_db/main.php | 5 +++-- contrib/news/main.php | 1 + contrib/numeric_score/main.php | 1 + contrib/random_image/main.php | 1 + contrib/rating/main.php | 1 + contrib/regen_thumb/main.php | 1 + contrib/site_description/main.php | 1 + ext/tag_list/main.php | 18 +++++++++++++++--- ext/upgrade/main.php | 3 ++- 16 files changed, 40 insertions(+), 9 deletions(-) diff --git a/contrib/ban_words/main.php b/contrib/ban_words/main.php index aee98417..f64b1f69 100644 --- a/contrib/ban_words/main.php +++ b/contrib/ban_words/main.php @@ -2,6 +2,7 @@ /* * Name: Comment Word Ban * Author: Shish + * Link: http://code.shishnet.org/shimmie2/ * License: GPLv2 * Description: For stopping spam and other comment abuse * Documentation: diff --git a/contrib/bulk_add/main.php b/contrib/bulk_add/main.php index 0fa89029..c31d43fb 100644 --- a/contrib/bulk_add/main.php +++ b/contrib/bulk_add/main.php @@ -2,6 +2,7 @@ /* * Name: Bulk Add * Author: Shish + * Link: http://code.shishnet.org/shimmie2/ * License: GPLv2 * Description: Bulk add server-side images * Documentation: @@ -30,7 +31,9 @@ class BulkAdd extends SimpleExtension { $this->theme->display_admin_block(); } - + /** + * Generate the necessary DataUploadEvent for a given image and tags. + */ private function add_image($tmpname, $filename, $tags) { assert(file_exists($tmpname)); diff --git a/contrib/et/main.php b/contrib/et/main.php index dd6babe2..088d21f6 100644 --- a/contrib/et/main.php +++ b/contrib/et/main.php @@ -29,6 +29,9 @@ class ET extends SimpleExtension { } } + /** + * Collect the information and return it in a keyed array. + */ private function get_info() { global $config, $database; global $_event_listeners; // yay for using secret globals \o/ diff --git a/contrib/featured/main.php b/contrib/featured/main.php index 12f06b08..83ace62e 100644 --- a/contrib/featured/main.php +++ b/contrib/featured/main.php @@ -2,6 +2,7 @@ /* * Name: Featured Image * Author: Shish + * Link: http://code.shishnet.org/shimmie2/ * License: GPLv2 * Description: Bring a specific image to the users' attentions * Documentation: diff --git a/contrib/handle_flash/main.php b/contrib/handle_flash/main.php index 013528ac..21b19b30 100644 --- a/contrib/handle_flash/main.php +++ b/contrib/handle_flash/main.php @@ -2,7 +2,8 @@ /* * Name: Handle Flash * Author: Shish - * Description: Handle Flash files + * Link: http://code.shishnet.org/shimmie2/ + * Description: Handle Flash files. (No thumbnail is generated for flash files) */ class FlashFileHandler extends DataHandlerExtension { diff --git a/contrib/handle_svg/main.php b/contrib/handle_svg/main.php index e2d02a3f..bab0cf14 100644 --- a/contrib/handle_svg/main.php +++ b/contrib/handle_svg/main.php @@ -2,7 +2,8 @@ /* * Name: Handle SVG * Author: Shish - * Description: Handle SVG files + * Link: http://code.shishnet.org/shimmie2/ + * Description: Handle SVG files. (No thumbnail is generated for SVG files) */ class SVGFileHandler implements Extension { diff --git a/contrib/ipban/main.php b/contrib/ipban/main.php index bd9a11d0..3af43ead 100644 --- a/contrib/ipban/main.php +++ b/contrib/ipban/main.php @@ -2,6 +2,7 @@ /* * Name: IP Ban * Author: Shish + * Link: http://code.shishnet.org/shimmie2/ * License: GPLv2 * Description: Ban IP addresses * Documentation: diff --git a/contrib/log_db/main.php b/contrib/log_db/main.php index 2e51ce24..da5a590c 100644 --- a/contrib/log_db/main.php +++ b/contrib/log_db/main.php @@ -1,8 +1,9 @@ + * Link: http://code.shishnet.org/shimmie2/ + * Description: Keep a record of SCore events (in the database). * Visibility: admin */ diff --git a/contrib/news/main.php b/contrib/news/main.php index 69c87255..bd3f8388 100644 --- a/contrib/news/main.php +++ b/contrib/news/main.php @@ -2,6 +2,7 @@ /* * Name: News * Author: Shish + * Link: http://code.shishnet.org/shimmie2/ * License: GPLv2 * Description: Show a short amount of text in a block on the post list * Documentation: diff --git a/contrib/numeric_score/main.php b/contrib/numeric_score/main.php index 0e7d5181..79a0ca35 100755 --- a/contrib/numeric_score/main.php +++ b/contrib/numeric_score/main.php @@ -2,6 +2,7 @@ /* * Name: Image Scores (Numeric) * Author: Shish + * Link: http://code.shishnet.org/shimmie2/ * License: GPLv2 * Description: Allow users to score images * Documentation: diff --git a/contrib/random_image/main.php b/contrib/random_image/main.php index bad07792..75fcccf0 100644 --- a/contrib/random_image/main.php +++ b/contrib/random_image/main.php @@ -2,6 +2,7 @@ /* * Name: Random Image * Author: Shish + * Link: http://code.shishnet.org/shimmie2/ * License: GPLv2 * Description: Do things with a random image * Documentation: diff --git a/contrib/rating/main.php b/contrib/rating/main.php index b246b14e..e672c311 100644 --- a/contrib/rating/main.php +++ b/contrib/rating/main.php @@ -2,6 +2,7 @@ /* * Name: Image Ratings * Author: Shish + * Link: http://code.shishnet.org/shimmie2/ * License: GPLv2 * Description: Allow users to rate images "safe", "questionable" or "explicit" */ diff --git a/contrib/regen_thumb/main.php b/contrib/regen_thumb/main.php index cf3e2eb6..22950666 100644 --- a/contrib/regen_thumb/main.php +++ b/contrib/regen_thumb/main.php @@ -2,6 +2,7 @@ /* * Name: Regen Thumb * Author: Shish + * Link: http://code.shishnet.org/shimmie2/ * License: GPLv2 * Description: Regenerate a thumbnail image * Documentation: diff --git a/contrib/site_description/main.php b/contrib/site_description/main.php index 43ed38b1..5f294e3b 100644 --- a/contrib/site_description/main.php +++ b/contrib/site_description/main.php @@ -2,6 +2,7 @@ /* * Name: Site Description * Author: Shish + * Link: http://code.shishnet.org/shimmie2/ * License: GPLv2 * Visibility: admin * Description: A description for search engines diff --git a/ext/tag_list/main.php b/ext/tag_list/main.php index c30aacb6..c7d57716 100644 --- a/ext/tag_list/main.php +++ b/ext/tag_list/main.php @@ -1,7 +1,8 @@ + * Link: http://code.shishnet.org/shimmie2/ * Description: Show the tags in various ways */ @@ -107,13 +108,18 @@ class TagList extends SimpleExtension { return make_link("post/list/$u_tag/1"); } + /** + * Get the minimum number of times a tag needs to be used + * in order to be considered in the tag list. + * @retval int + */ private function get_tags_min() { if(isset($_GET['mincount'])) { return int_escape($_GET['mincount']); } else { global $config; - return $config->get_int('tags_min'); + return $config->get_int('tags_min'); // get the default. } } @@ -170,6 +176,8 @@ class TagList extends SimpleExtension { $tags_min = $this->get_tags_min(); $starts_with = $this->get_starts_with(); + + // check if we have a cached version $cache_key = "data/tag_cloud-" . md5("tc" . $tags_min . $starts_with) . ".html"; if(file_exists($cache_key)) {return file_get_contents($cache_key);} @@ -205,6 +213,8 @@ class TagList extends SimpleExtension { $tags_min = $this->get_tags_min(); $starts_with = $this->get_starts_with(); + + // check if we have a cached version $cache_key = "data/tag_alpha-" . md5("ta" . $tags_min . $starts_with) . ".html"; if(file_exists($cache_key)) {return file_get_contents($cache_key);} @@ -239,6 +249,8 @@ class TagList extends SimpleExtension { global $database; $tags_min = $this->get_tags_min(); + + // check if we have a cached version $cache_key = "data/tag_popul-" . md5("tp" . $tags_min) . ".html"; if(file_exists($cache_key)) {return file_get_contents($cache_key);} diff --git a/ext/upgrade/main.php b/ext/upgrade/main.php index 35854e1d..7445d2d4 100644 --- a/ext/upgrade/main.php +++ b/ext/upgrade/main.php @@ -1,7 +1,8 @@ + * Link: http://code.shishnet.org/shimmie2/ * Description: Keeps things happy behind the scenes * Visibility: admin */