From 8546039b977dbe2471f3299b3750775418698c78 Mon Sep 17 00:00:00 2001 From: Alex Cabal Date: Fri, 15 Nov 2024 21:31:47 -0600 Subject: [PATCH] Comment formatting --- lib/RssFeed.php | 12 ++++-------- www/about/index.php | 4 ++-- www/artworks/edit.php | 4 ++-- www/artworks/get.php | 8 +++----- www/artworks/index.php | 3 +-- www/artworks/new.php | 6 +++--- www/artworks/post.php | 6 +++--- www/authors/get.php | 6 +++--- www/bulk-downloads/download.php | 5 ++--- www/bulk-downloads/get.php | 4 ++-- www/collections/get.php | 2 +- www/ebooks/download.php | 8 ++++---- www/ebooks/index.php | 7 +++---- www/feeds/atom/search.php | 2 -- www/feeds/download.php | 8 ++++---- www/feeds/opds/search.php | 2 -- www/feeds/rss/search.php | 2 -- 17 files changed, 37 insertions(+), 52 deletions(-) diff --git a/lib/RssFeed.php b/lib/RssFeed.php index f12c3c05..c0199b02 100644 --- a/lib/RssFeed.php +++ b/lib/RssFeed.php @@ -31,9 +31,9 @@ class RssFeed extends Feed{ } public function SaveIfChanged(): bool{ - // Did we actually update the feed? If so, write to file and update the index + // Did we actually update the feed? If so, write to file and update the index. if($this->HasChanged($this->Path)){ - // Files don't match, save the file + // Files don't match, save the file. $this->Save(); return true; } @@ -42,11 +42,7 @@ class RssFeed extends Feed{ } protected function HasChanged(string $path): bool{ - // RSS doesn't have information about when an item was updated, - // only when it was first published. So, we approximate on whether the feed - // has changed by looking at the length of the enclosed file. - // This can sometimes be the same even if the file has changed, but most of the time - // it also changes. + // RSS doesn't have information about when an item was updated, only when it was first published. So, we approximate on whether the feed has changed by looking at the length of the enclosed file. This can sometimes be the same even if the file has changed, but most of the time it also changes. if(!is_file($path)){ return true; @@ -75,7 +71,7 @@ class RssFeed extends Feed{ } } catch(Exception){ - // Invalid XML + // Invalid XML. return true; } diff --git a/www/about/index.php b/www/about/index.php index e4a582f6..f238945d 100644 --- a/www/about/index.php +++ b/www/about/index.php @@ -2,8 +2,8 @@ $patronsCircle = []; $anonymousPatronCount = 0; -// Get the Patrons Circle and try to sort by last name ascending -// See for Unicode character properties +// Get the Patrons Circle and try to sort by last name ascending. +// See for Unicode character properties. $patronsCircle = Db::Query(' SELECT if(p.AlternateName is not null, p.AlternateName, u.Name) as SortedName diff --git a/www/artworks/edit.php b/www/artworks/edit.php index ce2f6540..11b74a5a 100644 --- a/www/artworks/edit.php +++ b/www/artworks/edit.php @@ -21,7 +21,7 @@ try{ throw new Exceptions\InvalidPermissionsException(); } - // We got here because an artwork update had errors and the user has to try again + // We got here because an artwork update had errors and the user has to try again. if($exception){ http_response_code(422); session_unset(); @@ -34,7 +34,7 @@ catch(Exceptions\LoginRequiredException){ Template::RedirectToLogin(); } catch(Exceptions\InvalidPermissionsException){ - Template::Emit403(); // No permissions to edit artwork + Template::Emit403(); // No permissions to edit artwork. } ?> diff --git a/www/artworks/get.php b/www/artworks/get.php index 80bb0224..1c8a0458 100644 --- a/www/artworks/get.php +++ b/www/artworks/get.php @@ -40,18 +40,16 @@ try{ throw new Exceptions\InvalidPermissionsException(); } - // We got here because an artwork was successfully submitted + // We got here because an artwork was successfully submitted. if($isSaved){ session_unset(); } - // We got here because an artwork PATCH operation had errors and the user has to try again + // We got here because an artwork PATCH operation had errors and the user has to try again. if($exception){ http_response_code(422); - // Before we overwrite the original artwork with our new one, restore the old status, - // because if the new status is 'approved' then it will hide the status form entirely, - // which will be confusing. + // Before we overwrite the original artwork with our new one, restore the old status, because if the new status is 'approved' then it will hide the status form entirely, which will be confusing. $oldStatus = $artwork->Status; /** @var Artwork $artwork */ $artwork = $_SESSION['artwork'] ?? $artwork; diff --git a/www/artworks/index.php b/www/artworks/index.php index 9baf69b0..fa320902 100644 --- a/www/artworks/index.php +++ b/www/artworks/index.php @@ -24,8 +24,7 @@ try{ $perPage = ARTWORK_PER_PAGE; } - // If we're passed string values that are the same as the defaults, - // set them to null so that we can have cleaner query strings in the navigation footer + // If we're passed string values that are the same as the defaults, set them to null so that we can have cleaner query strings in the navigation footer. if($sort == Enums\ArtworkSortType::CreatedNewest){ $sort = null; } diff --git a/www/artworks/new.php b/www/artworks/new.php index 1811447a..1ddcba7e 100644 --- a/www/artworks/new.php +++ b/www/artworks/new.php @@ -18,14 +18,14 @@ try{ throw new Exceptions\InvalidPermissionsException(); } - // We got here because an artwork was successfully submitted + // We got here because an artwork was successfully submitted. if($isCreated){ http_response_code(201); $artwork = null; session_unset(); } - // We got here because an artwork submission had errors and the user has to try again + // We got here because an artwork submission had errors and the user has to try again. if($exception){ http_response_code(422); session_unset(); @@ -44,7 +44,7 @@ catch(Exceptions\LoginRequiredException){ Template::RedirectToLogin(); } catch(Exceptions\InvalidPermissionsException){ - Template::Emit403(); // No permissions to submit artwork + Template::Emit403(); // No permissions to submit artwork. } ?> diff --git a/www/artworks/post.php b/www/artworks/post.php index 6f8b8ee3..f9a59873 100644 --- a/www/artworks/post.php +++ b/www/artworks/post.php @@ -13,7 +13,7 @@ try{ throw new Exceptions\LoginRequiredException(); } - // POSTing a new artwork + // POSTing a new artwork. if($httpMethod == Enums\HttpMethod::Post){ if(!Session::$User->Benefits->CanUploadArtwork){ throw new Exceptions\InvalidPermissionsException(); @@ -44,7 +44,7 @@ try{ header('Location: /artworks/new'); } - // PUTing an artwork + // PUTing an artwork. if($httpMethod == Enums\HttpMethod::Put){ $originalArtwork = Artwork::GetByUrl(HttpInput::Str(GET, 'artist-url-name'), HttpInput::Str(GET, 'artwork-url-name')); @@ -84,7 +84,7 @@ try{ header('Location: ' . $artwork->Url); } - // PATCHing an artwork + // PATCHing an artwork. if($httpMethod == Enums\HttpMethod::Patch){ $artwork = Artwork::GetByUrl(HttpInput::Str(GET, 'artist-url-name'), HttpInput::Str(GET, 'artwork-url-name')); diff --git a/www/authors/get.php b/www/authors/get.php index 076530a2..7fb4a110 100644 --- a/www/authors/get.php +++ b/www/authors/get.php @@ -4,11 +4,11 @@ $author = ''; $authorUrl = ''; try{ - $urlPath = trim(str_replace('.', '', HttpInput::Str(GET, 'url-path') ?? ''), '/'); // Contains the portion of the URL (without query string) that comes after https://standardebooks.org/ebooks/ - $wwwFilesystemPath = EBOOKS_DIST_PATH . $urlPath; // Path to the deployed WWW files for this ebook + $urlPath = trim(str_replace('.', '', HttpInput::Str(GET, 'url-path') ?? ''), '/'); // Contains the portion of the URL (without query string) that comes after `https://standardebooks.org/ebooks/`. + $wwwFilesystemPath = EBOOKS_DIST_PATH . $urlPath; // Path to the deployed www files for this ebook. if($urlPath == '' || mb_stripos($wwwFilesystemPath, EBOOKS_DIST_PATH) !== 0 || !is_dir($wwwFilesystemPath)){ - // Ensure the path exists and that the root is in our www directory + // Ensure the path exists and that the root is in our www directory. throw new Exceptions\AuthorNotFoundException(); } diff --git a/www/bulk-downloads/download.php b/www/bulk-downloads/download.php index e03c9e84..eeeeb8c3 100644 --- a/www/bulk-downloads/download.php +++ b/www/bulk-downloads/download.php @@ -23,7 +23,7 @@ try{ } // Everything OK, serve the file using Apache. - // The xsendfile Apache module tells Apache to serve the file, including not-modified or etag headers. + // The `xsendfile` Apache module tells Apache to serve the file, including `not-modified` or `etag` headers. // Much more efficient than reading it in PHP and outputting it that way. header('X-Sendfile: ' . WEB_ROOT . $path); header('Content-Type: application/zip'); @@ -37,8 +37,7 @@ catch(Exceptions\LoginRequiredException){ else{ preg_match('|(^/bulk-downloads/[^/]+?)/|ius', $path, $matches); if(sizeof($matches) == 2){ - // If we arrived from the bulk-downloads page, - // Make the login form redirect to the bulk download root, instead of refreshing directly into a download + // If we arrived from the bulk-downloads page make the login form redirect to the bulk download root, instead of refreshing directly into a download. Template::RedirectToLogin(true, $matches[1]); } else{ diff --git a/www/bulk-downloads/get.php b/www/bulk-downloads/get.php index 618d65b6..b1780df6 100644 --- a/www/bulk-downloads/get.php +++ b/www/bulk-downloads/get.php @@ -15,7 +15,7 @@ try{ if($collectionUrlName !== null){ $collections = []; - // Get all collections and then find the specific one we're looking for + // Get all collections and then find the specific one we're looking for. try{ /** @var array $collections */ $collections = apcu_fetch('bulk-downloads-collections'); @@ -42,7 +42,7 @@ try{ if($authorUrlName !== null){ $authors = []; - // Get all authors and then find the specific one we're looking for + // Get all authors and then find the specific one we're looking for. try{ /** @var array $collections */ $collections = apcu_fetch('bulk-downloads-authors'); diff --git a/www/collections/get.php b/www/collections/get.php index 050022f3..45fa014d 100644 --- a/www/collections/get.php +++ b/www/collections/get.php @@ -8,7 +8,7 @@ try{ $collectionType = ''; $ebooks = Ebook::GetAllByCollection($collection); - // Get the *actual* name of the collection, in case there are accent marks (like "Arsène Lupin") + // Get the *actual* name of the collection, in case there are accent marks (like `Arsène Lupin`). if(sizeof($ebooks) > 0){ foreach($ebooks[0]->CollectionMemberships as $cm){ $c = $cm->Collection; diff --git a/www/ebooks/download.php b/www/ebooks/download.php index ad1c427b..6874743f 100644 --- a/www/ebooks/download.php +++ b/www/ebooks/download.php @@ -1,7 +1,7 @@ GetMimeType()); @@ -50,7 +50,7 @@ try{ exit(); } - // Increment local download count, expires in 2 weeks + // Increment local download count, expires in 2 weeks. $downloadCount++; setcookie('download-count', (string)$downloadCount, ['expires' => intval((new DateTimeImmutable('+2 week'))->format(Enums\DateTimeFormat::UnixTimestamp->value)), 'path' => '/', 'domain' => SITE_DOMAIN, 'secure' => true, 'httponly' => false, 'samesite' => 'Lax']); } diff --git a/www/ebooks/index.php b/www/ebooks/index.php index e71e3971..1fbc48ad 100644 --- a/www/ebooks/index.php +++ b/www/ebooks/index.php @@ -21,8 +21,7 @@ try{ $perPage = EBOOKS_PER_PAGE; } - // If we're passed string values that are the same as the defaults, - // set them to null so that we can have cleaner query strings in the navigation footer + // If we're passed string values that are the same as the defaults, set them to null so that we can have cleaner query strings in the navigation footer. if($view === Enums\ViewType::Grid){ $view = null; } @@ -99,8 +98,8 @@ catch(Exceptions\PageOutOfBoundsException){ exit(); } catch(Exceptions\AppException $ex){ - // Something very unexpected happened, log and emit 500 - http_response_code(500); // Internal server error + // Something very unexpected happened, log and emit 500. + http_response_code(500); // Internal server error. Log::WriteErrorLogEntry($ex); exit(); } diff --git a/www/feeds/atom/search.php b/www/feeds/atom/search.php index df77d3cd..b18576c2 100644 --- a/www/feeds/atom/search.php +++ b/www/feeds/atom/search.php @@ -1,6 +1,4 @@