PHPDoc update in app/blobs, app/page, app/upload and app/votes

qa-include/app/blobs.php

@@ -27,9 +27,9 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Return the URL which will output $blobid from the database when requested, $absolute or relative
- * @param $blobid
+ * @param string $blobid
  * @param bool $absolute
- * @return mixed|string
+ * @return string
  */
 function qa_get_blob_url($blobid, $absolute = false)
 {
@@ -41,8 +41,8 @@ function qa_get_blob_url($blobid, $absolute = false)
 
 /**
  * Return the full path to the on-disk directory for blob $blobid (subdirectories are named by the first 3 digits of $blobid)
- * @param $blobid
- * @return mixed|string
+ * @param string $blobid
+ * @return string
  */
 function qa_get_blob_directory($blobid)
 {
@@ -54,9 +54,9 @@ function qa_get_blob_directory($blobid)
 
 /**
  * Return the full page and filename of blob $blobid which is in $format ($format is used as the file name suffix e.g. .jpg)
- * @param $blobid
- * @param $format
- * @return mixed|string
+ * @param string $blobid
+ * @param string $format
+ * @return string
  */
 function qa_get_blob_filename($blobid, $format)
 {
@@ -69,13 +69,13 @@ function qa_get_blob_filename($blobid, $format)
 /**
  * Create a new blob (storing the content in the database or on disk as appropriate) with $content and $format, returning its blobid.
  * Pass the original name of the file uploaded in $sourcefilename and the $userid, $cookieid and $ip of the user creating it
- * @param $content
- * @param $format
- * @param $sourcefilename
- * @param $userid
- * @param $cookieid
- * @param $ip
- * @return mixed|null|string
+ * @param string $content
+ * @param string $format
+ * @param string|null $sourcefilename
+ * @param mixed|null $userid
+ * @param string|null $cookieid
+ * @param string $ip
+ * @return string
  */
 function qa_create_blob($content, $format, $sourcefilename = null, $userid = null, $cookieid = null, $ip = null)
 {
@@ -97,10 +97,10 @@ function qa_create_blob($content, $format, $sourcefilename = null, $userid = nul
 
 /**
  * Write the on-disk file for blob $blobid with $content and $format. Returns true if the write succeeded, false otherwise.
- * @param $blobid
- * @param $content
- * @param $format
- * @return bool|mixed
+ * @param string $blobid
+ * @param string $content
+ * @param string $format
+ * @return bool
  */
 function qa_write_blob_file($blobid, $content, $format)
 {
@@ -130,8 +130,8 @@ function qa_write_blob_file($blobid, $content, $format)
 
 /**
  * Retrieve blob $blobid from the database, reading the content from disk if appropriate
- * @param $blobid
- * @return array|mixed|null
+ * @param string $blobid
+ * @return array
  */
 function qa_read_blob($blobid)
 {
@@ -150,9 +150,9 @@ function qa_read_blob($blobid)
 
 /**
  * Read the content of blob $blobid in $format from disk. On failure, it will return false.
- * @param $blobid
- * @param $format
- * @return mixed|null|string
+ * @param string $blobid
+ * @param string $format
+ * @return false|string|null
  */
 function qa_read_blob_file($blobid, $format)
 {
@@ -168,7 +168,7 @@ function qa_read_blob_file($blobid, $format)
 
 /**
  * Delete blob $blobid from the database, and remove the on-disk file if appropriate
- * @param $blobid
+ * @param string $blobid
  * @return mixed
  */
 function qa_delete_blob($blobid)
@@ -190,8 +190,8 @@ function qa_delete_blob($blobid)
 
 /**
  * Delete the on-disk file for blob $blobid in $format
- * @param $blobid
- * @param $format
+ * @param string $blobid
+ * @param string $format
  * @return mixed
  */
 function qa_delete_blob_file($blobid, $format)
@@ -204,8 +204,8 @@ function qa_delete_blob_file($blobid, $format)
 
 /**
  * Check if blob $blobid exists
- * @param $blobid
- * @return bool|mixed
+ * @param string $blobid
+ * @return bool
  */
 function qa_blob_exists($blobid)
 {

qa-include/app/page.php

@@ -228,7 +228,7 @@ function qa_get_request_content()
 
 /**
  * Output the $qa_content via the theme class after doing some pre-processing, mainly relating to Javascript
- * @param $qa_content
+ * @param array $qa_content
  * @return mixed
  */
 function qa_output_content($qa_content)
@@ -382,7 +382,7 @@ function qa_output_content($qa_content)
 
 /**
  * Update any statistics required by the fields in $qa_content, and return true if something was done
- * @param $qa_content
+ * @param array $qa_content
  * @return bool
  */
 function qa_do_content_stats($qa_content)
@@ -487,7 +487,7 @@ function qa_controller_routing()
 
 /**
  * Sets the template which should be passed to the theme class, telling it which type of page it's displaying
- * @param $template
+ * @param string $template
  */
 function qa_set_template($template)
 {

qa-include/app/upload.php

@@ -55,12 +55,12 @@ function qa_get_max_upload_size()
  * 'height' => if an image, the height in pixels of the blob created (after possible scaling)
  * 'blobid' => the blobid that was created (if there was no error)
  * 'bloburl' => the url that can be used to view/download the created blob (if there was no error)
- * @param $localfilename
- * @param $sourcefilename
- * @param $maxfilesize
+ * @param string $localfilename
+ * @param string $sourcefilename
+ * @param int|null $maxfilesize
  * @param bool $onlyimage
- * @param $imagemaxwidth
- * @param $imagemaxheight
+ * @param int|null $imagemaxwidth
+ * @param int|null $imagemaxheight
  * @return array
  */
 function qa_upload_file($localfilename, $sourcefilename, $maxfilesize = null, $onlyimage = false, $imagemaxwidth = null, $imagemaxheight = null)
@@ -197,10 +197,10 @@ function qa_upload_file($localfilename, $sourcefilename, $maxfilesize = null, $o
 
 /**
  * In response to a file upload, move the first uploaded file into blob storage. Other parameters are as for qa_upload_file(...)
- * @param $maxfilesize
+ * @param int|null $maxfilesize
  * @param bool $onlyimage
- * @param $imagemaxwidth
- * @param $imagemaxheight
+ * @param int|null $imagemaxwidth
+ * @param int|null $imagemaxheight
  * @return array
  */
 function qa_upload_file_one($maxfilesize = null, $onlyimage = false, $imagemaxwidth = null, $imagemaxheight = null)

qa-include/app/votes.php

@@ -28,11 +28,11 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 /**
  * Check if $userid can vote on $post, on the page $topage.
  * Return an HTML error to display if there was a problem, or false if it's OK.
- * @param $post
- * @param $vote
- * @param $userid
- * @param $topage
- * @return bool|mixed|string
+ * @param array $post
+ * @param int $vote
+ * @param mixed $userid
+ * @param string $topage
+ * @return bool|string
  */
 function qa_vote_error_html($post, $vote, $userid, $topage)
 {
@@ -106,12 +106,12 @@ function qa_vote_error_html($post, $vote, $userid, $topage)
 /**
  * Actually set (application level) the $vote (-1/0/1) by $userid (with $handle and $cookieid) on $postid.
  * Handles user points, recounting and event reports as appropriate.
- * @param $post
- * @param $userid
- * @param $handle
- * @param $cookieid
- * @param $vote
- * @return void
+ * @param array $post
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
+ * @param int $vote
+ * @return mixed
  */
 function qa_vote_set($post, $userid, $handle, $cookieid, $vote)
 {
@@ -178,10 +178,10 @@ function qa_vote_set($post, $userid, $handle, $cookieid, $vote)
 /**
  * Check if $userid can flag $post, on the page $topage.
  * Return an HTML error to display if there was a problem, or false if it's OK.
- * @param $post
- * @param $userid
- * @param $topage
- * @return bool|mixed|string
+ * @param array $post
+ * @param mixed $userid
+ * @param string $topage
+ * @return bool|string|array
  */
 function qa_flag_error_html($post, $userid, $topage)
 {
@@ -228,11 +228,11 @@ function qa_flag_error_html($post, $userid, $topage)
  * Set (application level) a flag by $userid (with $handle and $cookieid) on $oldpost which belongs to $question.
  * Handles recounting, admin notifications and event reports as appropriate.
  * Returns true if the post should now be hidden because it has accumulated enough flags.
- * @param $oldpost
- * @param $userid
- * @param $handle
- * @param $cookieid
- * @param $question
+ * @param array $oldpost
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
+ * @param array $question
  * @return bool
  */
 function qa_flag_set_tohide($oldpost, $userid, $handle, $cookieid, $question)
@@ -278,10 +278,10 @@ function qa_flag_set_tohide($oldpost, $userid, $handle, $cookieid, $question)
 /**
  * Clear (application level) a flag on $oldpost by $userid (with $handle and $cookieid).
  * Handles recounting and event reports as appropriate.
- * @param $oldpost
- * @param $userid
- * @param $handle
- * @param $cookieid
+ * @param array $oldpost
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
  * @return mixed
  */
 function qa_flag_clear($oldpost, $userid, $handle, $cookieid)
@@ -320,10 +320,10 @@ function qa_flag_clear($oldpost, $userid, $handle, $cookieid)
 /**
  * Clear (application level) all flags on $oldpost by $userid (with $handle and $cookieid).
  * Handles recounting and event reports as appropriate.
- * @param $oldpost
- * @param $userid
- * @param $handle
- * @param $cookieid
+ * @param array $oldpost
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
  * @return mixed
  */
 function qa_flags_clear_all($oldpost, $userid, $handle, $cookieid)