From 2fc3fbb41dbd81a92dfe27a22b31f36b10ea37ca Mon Sep 17 00:00:00 2001 From: Juuso Lapinlampi Date: Mon, 23 May 2016 21:02:39 +0000 Subject: Extend and improve PHP code comments (PHPDoc) Add file summaries, @copyright tags and other comments. Covers majority of the PHP code base now. I have avoided being too verbose and omitted some potential tags. Most visibly to the user, this comments every user configurable setting and clarifies what some of the options do. POMF_DB_USER and POMF_DB_PASS are not rendered perfectly in phpDocumentor version 2.8.5. This is a sacrifice I made in attempt for not being too verbose and obvious. Response class gets a @todo for being a god object. --- static/classes/Response.class.php | 75 +++++++++++++++++++++++++++++++- static/classes/UploadException.class.php | 8 ++-- static/classes/UploadedFile.class.php | 12 +++-- 3 files changed, 87 insertions(+), 8 deletions(-) (limited to 'static/classes') diff --git a/static/classes/Response.class.php b/static/classes/Response.class.php index f8555d6..fdf57e6 100755 --- a/static/classes/Response.class.php +++ b/static/classes/Response.class.php @@ -1,8 +1,11 @@ - * Copyright (c) 2015, 2016 the Pantsu.cat developers + * Prints file upload API responses depending on desired response type format. + * + * @copyright Copyright (c) 2015 cenci0 + * @copyright Copyright (c) 2015, 2016 the Pantsu.cat developers + * * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -23,10 +26,30 @@ * SOFTWARE. */ +/** + * The Response class is a do-it-all for getting responses out in different + * formats. + * + * @todo Create sub-classes to split and extend this god object. + */ class Response { + /** + * Indicates response type used for routing. + * + * Valid strings are 'csv', 'html', 'json' and 'text'. + * + * @var string $type Response type + */ private $type; + /** + * Indicates requested response type. + * + * Valid strings are 'csv', 'html', 'json', 'gyazo' and 'text'. + * + * @param string|null $response_type Response type + */ public function __construct($response_type = null) { switch ($response_type) { @@ -59,6 +82,13 @@ class Response } } + /** + * Routes error messages depending on response type. + * + * @param int $code HTTP status code number. + * @param int $desc Descriptive error message. + * @return void + */ public function error($code, $desc) { $response = null; @@ -82,6 +112,12 @@ class Response echo $response; } + /** + * Routes success messages depending on response type. + * + * @param mixed[] $files + * @return void + */ public function send($files) { $response = null; @@ -106,7 +142,11 @@ class Response } /** + * Indicates with CSV body the request was invalid. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param int $description Descriptive error message. + * @return string Error message in CSV format. */ private static function csv_error($description) { @@ -114,7 +154,11 @@ class Response } /** + * Indicates with CSV body the request was successful. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param mixed[] $files + * @return string Success message in CSV format. */ private static function csv_success($files) { @@ -130,7 +174,12 @@ class Response } /** + * Indicates with HTML body the request was invalid. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param int $code HTTP status code number. + * @param int $description Descriptive error message. + * @return string Error message in HTML format. */ private static function html_error($code, $description) { @@ -138,7 +187,11 @@ class Response } /** + * Indicates with HTML body the request was successful. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param mixed[] $files + * @return string Success message in HTML format. */ private static function html_success($files) { @@ -152,7 +205,12 @@ class Response } /** + * Indicates with JSON body the request was invalid. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param int $code HTTP status code number. + * @param int $description Descriptive error message. + * @return string Error message in pretty-printed JSON format. */ private static function json_error($code, $description) { @@ -164,7 +222,11 @@ class Response } /** + * Indicates with JSON body the request was successful. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param mixed[] $files + * @return string Success message in pretty-printed JSON format. */ private static function json_success($files) { @@ -175,7 +237,12 @@ class Response } /** + * Indicates with plain text body the request was invalid. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param int $code HTTP status code number. + * @param int $description Descriptive error message. + * @return string Error message in plain text format. */ private static function text_error($code, $description) { @@ -183,7 +250,11 @@ class Response } /** + * Indicates with plain text body the request was successful. + * * @deprecated 2.1.0 Will be renamed to camelCase format. + * @param mixed[] $files + * @return string Success message in plain text format. */ private static function text_success($files) { diff --git a/static/classes/UploadException.class.php b/static/classes/UploadException.class.php index dbe47eb..7740ee6 100755 --- a/static/classes/UploadException.class.php +++ b/static/classes/UploadException.class.php @@ -1,6 +1,11 @@ + * @author Michiel Thalen + * @copyright * -------------------------------------------------------------------- * The PHP License, version 3.01 * Copyright (c) 1999 - 2014 The PHP Group. All rights reserved. @@ -71,9 +76,6 @@ * . */ -// Exception class extension from: http://php.net/manual/en/features.file-upload.errors.php#89374 -// Handles files error returning a proper error description - class UploadException extends Exception { public function __construct($code) diff --git a/static/classes/UploadedFile.class.php b/static/classes/UploadedFile.class.php index 99020ce..1149581 100644 --- a/static/classes/UploadedFile.class.php +++ b/static/classes/UploadedFile.class.php @@ -1,7 +1,9 @@ + * Returns information about uploaded files. + * + * @copyright Copyright (c) 2013, 2014 Peter Lejeck * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -31,14 +33,18 @@ class UploadedFile public $tempfile; public $error; - /* Cached checksums */ + /** + * SHA-1 checksum + * + * @var string 40 digit hexadecimal hash (160 bits) + */ private $sha1; /** * Generates the SHA1 or returns the cached SHA1 hash for the file. * * @deprecated 2.1.0 To be replaced with SHA-256 hashing. - * @return string + * @return string|false $sha1 */ public function get_sha1() { -- cgit v1.2.3