From cdcd762a52d80d637a90acacda220ec471f8c3f8 Mon Sep 17 00:00:00 2001
From: Shish <shish@shishnet.org>
Date: Sun, 27 Sep 2015 02:17:44 +0100
Subject: [PATCH] more comments

---
 core/basethemelet.class.php |  6 +++---
 core/extension.class.php    |  2 +-
 core/imageboard.pack.php    | 31 +++++++++++++++++++++----------
 core/page.class.php         |  4 ++++
 ext/bbcode/main.php         |  2 +-
 ext/bulk_add_csv/main.php   |  8 ++++++++
 ext/comment/main.php        | 21 ++++++++++++++++-----
 7 files changed, 54 insertions(+), 20 deletions(-)

diff --git a/core/basethemelet.class.php b/core/basethemelet.class.php
index 19b17e6c..9bfb1a18 100644
--- a/core/basethemelet.class.php
+++ b/core/basethemelet.class.php
@@ -96,7 +96,7 @@ class BaseThemelet {
 	 *
 	 * @param string $base_url
 	 * @param string $query
-	 * @param int|string $page
+	 * @param string $page
 	 * @param string $name
 	 * @return string
 	 */
@@ -108,8 +108,8 @@ class BaseThemelet {
 	/**
 	 * @param string $base_url
 	 * @param string $query
-	 * @param int|string $page
-	 * @param int|string $current_page
+	 * @param string $page
+	 * @param int $current_page
 	 * @param string $name
 	 * @return string
 	 */
diff --git a/core/extension.class.php b/core/extension.class.php
index eff3f6ca..06c2c5b5 100644
--- a/core/extension.class.php
+++ b/core/extension.class.php
@@ -282,7 +282,7 @@ abstract class DataHandlerExtension extends Extension {
 	abstract protected function supported_ext($ext);
 
 	/**
-	 * @param $tmpname
+	 * @param string $tmpname
 	 * @return bool
 	 */
 	abstract protected function check_contents($tmpname);
diff --git a/core/imageboard.pack.php b/core/imageboard.pack.php
index 985c9b25..63c76e1a 100644
--- a/core/imageboard.pack.php
+++ b/core/imageboard.pack.php
@@ -192,6 +192,13 @@ class Image {
 		return ($yays > 1 || $nays > 0);
 	}
 
+	/**
+	 * @param string[] $tags
+	 * @param int $offset
+	 * @param int $limit
+	 * @return null|PDOStatement
+	 * @throws SCoreException
+	 */
 	public function get_accelerated_result($tags, $offset, $limit) {
 		global $database;
 
@@ -244,7 +251,7 @@ class Image {
 	 * Count the number of image results for a given search
 	 *
 	 * @param string[] $tags
-	 * @return mixed
+	 * @return int
 	 */
 	public static function count_images($tags=array()) {
 		assert('is_array($tags)');
@@ -401,9 +408,9 @@ class Image {
 	/**
 	 * Check configured template for a link, then try nice URL, then plain URL
 	 *
-	 * @param $template
-	 * @param $nice
-	 * @param $plain
+	 * @param string $template
+	 * @param string $nice
+	 * @param string $plain
 	 * @return string
 	 */
 	private function get_link($template, $nice, $plain) {
@@ -532,6 +539,10 @@ class Image {
 		return $this->locked;
 	}
 
+	/**
+	 * @param bool $tf
+	 * @throws SCoreException
+	 */
 	public function set_locked($tf) {
 		global $database;
 		$ln = $tf ? "Y" : "N";
@@ -1102,7 +1113,7 @@ class Tag {
 	 * Remove any excess fluff from a user-input tag
 	 *
 	 * @param string $tag
-	 * @return mixed
+	 * @return string
 	 */
 	public static function sanitise($tag) {
 		assert('is_string($tag)');
@@ -1118,7 +1129,7 @@ class Tag {
 	 *
 	 * @param string|string[] $tags
 	 * @param bool $tagme
-	 * @return array
+	 * @return string[]
 	 */
 	public static function explode($tags, $tagme=true) {
 		assert('is_string($tags) || is_array($tags)');
@@ -1307,9 +1318,9 @@ function add_dir(/*string*/ $base) {
 }
 
 /**
- * @param $tmpname
- * @param $filename
- * @param $tags
+ * @param string $tmpname
+ * @param string $filename
+ * @param string $tags
  * @throws UploadException
  */
 function add_image(/*string*/ $tmpname, /*string*/ $filename, /*string*/ $tags) {
@@ -1337,7 +1348,7 @@ function add_image(/*string*/ $tmpname, /*string*/ $filename, /*string*/ $tags)
  *
  * @param int $orig_width
  * @param int $orig_height
- * @return array
+ * @return int[]
  */
 function get_thumbnail_size(/*int*/ $orig_width, /*int*/ $orig_height) {
 	global $config;
diff --git a/core/page.class.php b/core/page.class.php
index 3d35fee5..cca68f63 100644
--- a/core/page.class.php
+++ b/core/page.class.php
@@ -205,6 +205,10 @@ class Page {
 		$this->cookies[] = array($full_name, $value, $time, $path);
 	}
 
+	/**
+	 * @param string $name
+	 * @return string|null
+	 */
 	public function get_cookie(/*string*/ $name) {
 		$full_name = COOKIE_PREFIX."_".$name;
 		if(isset($_COOKIE[$full_name])) {
diff --git a/ext/bbcode/main.php b/ext/bbcode/main.php
index 6c4d404e..ee20fa7c 100644
--- a/ext/bbcode/main.php
+++ b/ext/bbcode/main.php
@@ -93,7 +93,7 @@ class BBCode extends FormatterExtension {
 
 	/**
 	 * @param string $text
-	 * @return mixed
+	 * @return string
 	 */
 	private function filter_spoiler(/*string*/ $text) {
 		return str_replace(
diff --git a/ext/bulk_add_csv/main.php b/ext/bulk_add_csv/main.php
index 7fd6d2a7..34645e91 100644
--- a/ext/bulk_add_csv/main.php
+++ b/ext/bulk_add_csv/main.php
@@ -54,6 +54,14 @@ class BulkAddCSV extends Extension {
 
 	/**
 	 * Generate the necessary DataUploadEvent for a given image and tags.
+	 *
+	 * @param string $tmpname
+	 * @param string $filename
+	 * @param string $tags
+	 * @param string $source
+	 * @param string $rating
+	 * @param string $thumbfile
+	 * @throws UploadException
 	 */
 	private function add_image($tmpname, $filename, $tags, $source, $rating, $thumbfile) {
 		assert(file_exists($tmpname));
diff --git a/ext/comment/main.php b/ext/comment/main.php
index 08b50684..a36f2166 100644
--- a/ext/comment/main.php
+++ b/ext/comment/main.php
@@ -71,7 +71,7 @@ class Comment {
 	}
 
 	/**
-	 * @param \User $user
+	 * @param User $user
 	 * @return mixed
 	 */
 	public static function count_comments_by_user($user) {
@@ -393,7 +393,7 @@ class CommentList extends Extension {
 	/**
 	 * @param string $query
 	 * @param array $args
-	 * @return array
+	 * @return Comment[]
 	 */
 	private function get_generic_comments($query, $args) {
 		global $database;
@@ -407,7 +407,7 @@ class CommentList extends Extension {
 
 	/**
 	 * @param int $count
-	 * @return array
+	 * @return Comment[]
 	 */
 	private function get_recent_comments($count) {
 		return $this->get_generic_comments("
@@ -427,7 +427,7 @@ class CommentList extends Extension {
 	 * @param int $user_id
 	 * @param int $count
 	 * @param int $offset
-	 * @return array
+	 * @return Comment[]
 	 */
 	private function get_user_comments(/*int*/ $user_id, /*int*/ $count, /*int*/ $offset=0) {
 		return $this->get_generic_comments("
@@ -446,7 +446,7 @@ class CommentList extends Extension {
 
 	/**
 	 * @param int $image_id
-	 * @return array
+	 * @return Comment[]
 	 */
 	private function get_comments(/*int*/ $image_id) {
 		return $this->get_generic_comments("
@@ -464,6 +464,9 @@ class CommentList extends Extension {
 // }}}
 
 // add / remove / edit comments {{{
+	/**
+	 * @return bool
+	 */
 	private function is_comment_limit_hit() {
 		global $config, $database;
 
@@ -499,6 +502,8 @@ class CommentList extends Extension {
 	 * many times.
 	 *
 	 * FIXME: assumes comments are posted via HTTP...
+	 *
+	 * @return string
 	 */
 	public static function get_hash() {
 		return md5($_SERVER['REMOTE_ADDR'] . date("%Y%m%d"));
@@ -590,6 +595,12 @@ class CommentList extends Extension {
 		log_info("comment", "Comment #$cid added to Image #$image_id: $snippet", false, array("image_id"=>$image_id, "comment_id"=>$cid));
 	}
 
+	/**
+	 * @param int $image_id
+	 * @param User $user
+	 * @param string $comment
+	 * @throws CommentPostingException
+	 */
 	private function comment_checks(/*int*/ $image_id, User $user, /*string*/ $comment) {
 		global $config, $page;