From 5dd3c6e85262925cdbfd8fd4220706a034409f33 Mon Sep 17 00:00:00 2001 From: Dale Davies Date: Fri, 4 Feb 2022 11:52:57 +0000 Subject: [PATCH] Add/improve code documentation --- jumpapp/assets/css/styles.css | 7 +++++++ jumpapp/assets/js/index.js | 7 ++++++- jumpapp/background-css.php | 7 +++++++ jumpapp/classes/Background.php | 20 ++++++++++++++++++++ jumpapp/classes/Cache.php | 7 +++++++ jumpapp/classes/Config.php | 10 ++++++++++ jumpapp/classes/Greeting.php | 13 +++++++++++++ jumpapp/classes/Site.php | 7 +++++++ jumpapp/classes/Sites.php | 8 +++++--- jumpapp/config.php | 13 ++++++++++++- jumpapp/index.php | 7 +++++++ 11 files changed, 101 insertions(+), 5 deletions(-) diff --git a/jumpapp/assets/css/styles.css b/jumpapp/assets/css/styles.css index 122767f..1966a8c 100644 --- a/jumpapp/assets/css/styles.css +++ b/jumpapp/assets/css/styles.css @@ -1,3 +1,10 @@ +/** + * Some CSS because Jump would look pretty ugly without it. + * + * @author Dale Davies + * @license MIT + */ + * { box-sizing: border-box; } diff --git a/jumpapp/assets/js/index.js b/jumpapp/assets/js/index.js index 7bed246..a6359ac 100644 --- a/jumpapp/assets/js/index.js +++ b/jumpapp/assets/js/index.js @@ -1 +1,6 @@ -console.log('yay'); \ No newline at end of file +/** + * One day some javascript mught live here. + * + * @author Dale Davies + * @license MIT + */ \ No newline at end of file diff --git a/jumpapp/background-css.php b/jumpapp/background-css.php index 76dd951..3e64b01 100644 --- a/jumpapp/background-css.php +++ b/jumpapp/background-css.php @@ -1,4 +1,11 @@ + * @license MIT + */ + // Provided by composer for psr-4 style autoloading. require __DIR__ .'/vendor/autoload.php'; diff --git a/jumpapp/classes/Background.php b/jumpapp/classes/Background.php index 8f3f41c..2726ffc 100644 --- a/jumpapp/classes/Background.php +++ b/jumpapp/classes/Background.php @@ -2,6 +2,13 @@ namespace Jump; +/** + * Return a random background image path selected from the list of files + * found in the /assets/backgrounds directory. + * + * @author Dale Davies + * @license MIT + */ class Background { private string $backgroundsdirectory; @@ -14,10 +21,23 @@ class Background { $this->enumerate_files(); } + /** + * Enumerate a list of background filenames from backgrounds directory. + * + * @return void + */ private function enumerate_files(): void { $this->backgroundfiles = array_diff(scandir($this->backgroundsdirectory), array('..', '.')); } + /** + * Select a random file from the enumerated list in $this->backgroundfiles + * and optionally prefix with a web accessible path for the backgrounds + * directory. + * + * @param boolean $includepath Should the backgrounds directory path be prefixed? + * @return string The selected background image filename/, optionally including path. + */ public function get_random_background_file(bool $includepath = true): string { return ($includepath ? $this->webaccessibledir : '') . '/'. $this->backgroundfiles[array_rand($this->backgroundfiles)]; diff --git a/jumpapp/classes/Cache.php b/jumpapp/classes/Cache.php index d6641c5..18f7118 100644 --- a/jumpapp/classes/Cache.php +++ b/jumpapp/classes/Cache.php @@ -4,6 +4,13 @@ namespace Jump; use Nette\Caching; +/** + * Defines caches to be used throughout the site and provides a wrapper around + * the Nette\Caching library. + * + * @author Dale Davies + * @license MIT + */ class Cache { private Caching\Storages\FileStorage $storage; diff --git a/jumpapp/classes/Config.php b/jumpapp/classes/Config.php index 2e77013..a865380 100644 --- a/jumpapp/classes/Config.php +++ b/jumpapp/classes/Config.php @@ -4,6 +4,16 @@ namespace Jump; use Exception; +/** + * Load, parse and enumerate all configuration paramaters requires throughout + * the application. Validates the config.php on load to ensure required params + * are all present. + * + * Provides a simple interface for retriving config paramaters once initialised. + * + * @author Dale Davies + * @license MIT + */ class Config { private \PHLAK\Config\Config $config; diff --git a/jumpapp/classes/Greeting.php b/jumpapp/classes/Greeting.php index e4805f7..1de099c 100644 --- a/jumpapp/classes/Greeting.php +++ b/jumpapp/classes/Greeting.php @@ -2,6 +2,13 @@ namespace Jump; +/** + * Choose the appropriate greeting word for the time of day, so if the current + * hour is 04:00 this will return "morning" etc. + * + * @author Dale Davies + * @license MIT + */ class Greeting { private array $greetings; @@ -14,6 +21,12 @@ class Greeting { ]; } + /** + * Select the appropriate greeting word based on the time of day and + * what has been defined in $this->greetings. + * + * @return string The greeting word selected. + */ public function get_greeting(): string { krsort($this->greetings); foreach ($this->greetings as $key => $value) { diff --git a/jumpapp/classes/Site.php b/jumpapp/classes/Site.php index 63bc0b0..7b4eb87 100644 --- a/jumpapp/classes/Site.php +++ b/jumpapp/classes/Site.php @@ -2,6 +2,13 @@ namespace Jump; +/** + * Parse the data required to represent a site and provide method for generating + * and/or retrieving the site's icon. + * + * @author Dale Davies + * @license MIT + */ class Site { public string $name; diff --git a/jumpapp/classes/Sites.php b/jumpapp/classes/Sites.php index 41f769f..c3d1cb3 100644 --- a/jumpapp/classes/Sites.php +++ b/jumpapp/classes/Sites.php @@ -5,9 +5,11 @@ namespace Jump; use Exception; /** - * Represents the sites defined in sites.json + * Loads, validates and caches the site data defined in sites.json + * into an array of Site objects. * - * @author Dale Davies {@link https://www.daledavies.co.uk} + * @author Dale Davies + * @license MIT */ class Sites { @@ -70,7 +72,7 @@ class Sites { * Given a URL, does that site exist in our list of sites? * * @param string $url The URL to search for. - * @return Site|null + * @return Site */ public function get_site_by_url(string $url): Site { $found = array_search($url, array_column($this->get_sites(), 'url')); diff --git a/jumpapp/config.php b/jumpapp/config.php index aa1787a..a0a2161 100644 --- a/jumpapp/config.php +++ b/jumpapp/config.php @@ -1,9 +1,20 @@ + * @license MIT + */ + return [ + // The site name is displayed in the browser tab. 'sitename' => getenv('SITENAME') ?: 'Jump', + // Where on the this code is located. 'wwwroot' => getenv('WWWROOT') ?: '/var/www/html', + // Stop retrieving items from the cache, useful for testing. 'cachebypass' => getenv('CACHEBYPASS') ?: false, + // Where is the cache storage directory, should not be public. 'cachedir' => getenv('CACHEDIR') ?: '/var/www/cache', + // Include the robots noindex meta tag in site header. 'noindex' => getenv('NOINDEX') ?: true, ]; \ No newline at end of file diff --git a/jumpapp/index.php b/jumpapp/index.php index 2b6e40d..94f3fd1 100644 --- a/jumpapp/index.php +++ b/jumpapp/index.php @@ -1,4 +1,11 @@ + * @license MIT + */ + // Provided by composer for psr-4 style autoloading. require __DIR__ .'/vendor/autoload.php';