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 From 118e7a7e53f32cc4ed76ec164de4835619d319d4 Mon Sep 17 00:00:00 2001 From: Juuso Lapinlampi Date: Mon, 23 May 2016 21:21:14 +0000 Subject: Add Pantsu.cat copyright year 2016 for recent change Claiming copyright for parts of UploadedFile.class.php and settings.inc.php as per previous change, which introduced PHPDoc comments. The other files where edits were made in previous commits are non-substantial and thus most likely not under copyright. --- static/classes/UploadedFile.class.php | 2 ++ 1 file changed, 2 insertions(+) (limited to 'static/classes') diff --git a/static/classes/UploadedFile.class.php b/static/classes/UploadedFile.class.php index 1149581..8c80b4a 100644 --- a/static/classes/UploadedFile.class.php +++ b/static/classes/UploadedFile.class.php @@ -4,6 +4,8 @@ * Returns information about uploaded files. * * @copyright Copyright (c) 2013, 2014 Peter Lejeck + * @copyright Copyright (c) 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 -- cgit v1.2.3 From f5f387293f67b6d0fcd2f34a5d118db88ef9660c Mon Sep 17 00:00:00 2001 From: Juuso Lapinlampi Date: Mon, 23 May 2016 21:26:06 +0000 Subject: UploadedFile: Fix typo SHA1 to SHA-1 This typo has been around for a while. Well, not anymore. --- static/classes/UploadedFile.class.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'static/classes') diff --git a/static/classes/UploadedFile.class.php b/static/classes/UploadedFile.class.php index 8c80b4a..20d42b3 100644 --- a/static/classes/UploadedFile.class.php +++ b/static/classes/UploadedFile.class.php @@ -43,7 +43,7 @@ class UploadedFile private $sha1; /** - * Generates the SHA1 or returns the cached SHA1 hash for the file. + * Generates the SHA-1 or returns the cached SHA-1 hash for the file. * * @deprecated 2.1.0 To be replaced with SHA-256 hashing. * @return string|false $sha1 -- cgit v1.2.3 From 4606553f38909b483bc06674f9558ede1a9ff1f6 Mon Sep 17 00:00:00 2001 From: Juuso Lapinlampi Date: Wed, 25 May 2016 03:12:40 +0000 Subject: Response: Clarify what http_response_code(200); is Add a comment explaining how HTTP status code 200 means success. --- static/classes/Response.class.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'static/classes') diff --git a/static/classes/Response.class.php b/static/classes/Response.class.php index fdf57e6..081baa6 100755 --- a/static/classes/Response.class.php +++ b/static/classes/Response.class.php @@ -137,7 +137,7 @@ class Response break; } - http_response_code(200); + http_response_code(200); // "200 OK". Success. echo $response; } -- cgit v1.2.3