Merge pull request #108 from green-ponies/master

More comments on functions.

contrib/ban_words/main.php

@@ -2,6 +2,7 @@
 /*
  * Name: Comment Word Ban
  * Author: Shish <webmaster@shishnet.org>
+ * Link: http://code.shishnet.org/shimmie2/
  * License: GPLv2
  * Description: For stopping spam and other comment abuse
  * Documentation:

contrib/bulk_add/main.php

@@ -2,6 +2,7 @@
 /*
  * Name: Bulk Add
  * Author: Shish <webmaster@shishnet.org>
+ * 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));
 

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/

contrib/featured/main.php

@@ -2,6 +2,7 @@
 /*
  * Name: Featured Image
  * Author: Shish <webmaster@shishnet.org>
+ * Link: http://code.shishnet.org/shimmie2/
  * License: GPLv2
  * Description: Bring a specific image to the users' attentions
  * Documentation:

contrib/handle_flash/main.php

@@ -2,7 +2,8 @@
 /*
  * Name: Handle Flash
  * Author: Shish <webmaster@shishnet.org>
- * 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 {

contrib/handle_svg/main.php

@@ -2,7 +2,8 @@
 /*
  * Name: Handle SVG
  * Author: Shish <webmaster@shishnet.org>
- * 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 {

contrib/ipban/main.php

@@ -2,6 +2,7 @@
 /*
  * Name: IP Ban
  * Author: Shish <webmaster@shishnet.org>
+ * Link: http://code.shishnet.org/shimmie2/
  * License: GPLv2
  * Description: Ban IP addresses
  * Documentation:

contrib/log_db/main.php

@@ -1,8 +1,9 @@
 <?php
 /*
  * Name: Logging (Database)
- * Author: Shish
+ * Author: Shish <webmaster@shishnet.org>
- * Description: Keep a record of SCore events
+ * Link: http://code.shishnet.org/shimmie2/
+ * Description: Keep a record of SCore events (in the database).
  * Visibility: admin
  */
 

contrib/news/main.php

@@ -2,6 +2,7 @@
 /*
  * Name: News
  * Author: Shish <webmaster@shishnet.org>
+ * Link: http://code.shishnet.org/shimmie2/
  * License: GPLv2
  * Description: Show a short amount of text in a block on the post list
  * Documentation:

contrib/numeric_score/main.php

@@ -2,6 +2,7 @@
 /*
  * Name: Image Scores (Numeric)
  * Author: Shish <webmaster@shishnet.org>
+ * Link: http://code.shishnet.org/shimmie2/
  * License: GPLv2
  * Description: Allow users to score images
  * Documentation:

contrib/random_image/main.php

@@ -2,6 +2,7 @@
 /*
  * Name: Random Image
  * Author: Shish <webmaster@shishnet.org>
+ * Link: http://code.shishnet.org/shimmie2/
  * License: GPLv2
  * Description: Do things with a random image
  * Documentation:

contrib/rating/main.php

@@ -2,6 +2,7 @@
 /*
  * Name: Image Ratings
  * Author: Shish <webmaster@shishnet.org>
+ * Link: http://code.shishnet.org/shimmie2/
  * License: GPLv2
  * Description: Allow users to rate images "safe", "questionable" or "explicit"
  */

contrib/regen_thumb/main.php

@@ -2,6 +2,7 @@
 /*
  * Name: Regen Thumb
  * Author: Shish <webmaster@shishnet.org>
+ * Link: http://code.shishnet.org/shimmie2/
  * License: GPLv2
  * Description: Regenerate a thumbnail image
  * Documentation:

contrib/site_description/main.php

@@ -2,6 +2,7 @@
 /*
  * Name: Site Description
  * Author: Shish <webmaster@shishnet.org>
+ * Link: http://code.shishnet.org/shimmie2/
  * License: GPLv2
  * Visibility: admin
  * Description: A description for search engines

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);
 	}

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");
 	}

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("<script>base_href = '$data_href';</script>");
+		$this->add_html_header("<script type='text/javascript'>base_href = '$data_href';</script>");
 		
 		/* Attempt to cache the CSS & JavaScript files */
 		if ($this->add_cached_auto_html_headers() === FALSE) {

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;

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();

ext/tag_list/main.php

@@ -1,7 +1,8 @@
 <?php
-/*
+/**
  * Name: Tag List
- * Author: Shish
+ * Author: Shish <webmaster@shishnet.org>
+ * 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);}
 

ext/upgrade/main.php

@@ -1,7 +1,8 @@
 <?php
 /*
  * Name: Database Upgrader
- * Author: Shish
+ * Author: Shish <webmaster@shishnet.org>
+ * Link: http://code.shishnet.org/shimmie2/
  * Description: Keeps things happy behind the scenes
  * Visibility: admin
  */

ext/upload/main.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * Name: Uploader
  * Author: Shish
  * Description: Allows people to upload files to the website
@@ -218,14 +218,28 @@ class Upload extends SimpleExtension {
 	}
 // }}}
 // do things {{{
+
+	/**
+	 * Check if a given user can upload.
+	 * @param $user The user to check.
+	 * @retval bool
+	 */
 	private function can_upload(User $user) {
 		global $config;
 		return ($config->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
+	 * Returns a descriptive error message for the specified PHP error code.
-	// TODO: Make these messages user/admin editable
+	 *
+	 * 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;