From 5af54bb9e091d2a6166f30044e6e370a6c792920 Mon Sep 17 00:00:00 2001
From: "green-ponies (jgen)" <jgen.tech@gmail.com>
Date: Tue, 7 Feb 2012 20:05:38 -0500
Subject: [PATCH] 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();