Add/improve code documentation

jumpapp/assets/css/styles.css

@@ -1,3 +1,10 @@
+/**
+ * Some CSS because Jump would look pretty ugly without it.
+ *
+ * @author Dale Davies <dale@daledavies.co.uk>
+ * @license MIT
+ */
+
 * {
     box-sizing: border-box;
 }

jumpapp/assets/js/index.js

@@ -1 +1,6 @@
-console.log('yay');
+/**
+ * One day some javascript mught live here.
+ *
+ * @author Dale Davies <dale@daledavies.co.uk>
+ * @license MIT
+ */

jumpapp/background-css.php

@@ -1,4 +1,11 @@
 <?php
+/**
+ * Generate dynamic CSS for randomising the background image.
+ *
+ * @author Dale Davies <dale@daledavies.co.uk>
+ * @license MIT
+ */
+
 // Provided by composer for psr-4 style autoloading.
 require __DIR__ .'/vendor/autoload.php';
 

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 <dale@daledavies.co.uk>
+ * @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)];

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 <dale@daledavies.co.uk>
+ * @license MIT
+ */
 class Cache {
 
     private Caching\Storages\FileStorage $storage;

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 <dale@daledavies.co.uk>
+ * @license MIT
+ */
 class Config {
 
     private \PHLAK\Config\Config $config;

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 <dale@daledavies.co.uk>
+ * @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) {

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 <dale@daledavies.co.uk>
+ * @license MIT
+ */
 class Site {
 
     public string $name;

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 <dale@daledavies.co.uk>
+ * @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'));

jumpapp/config.php

@@ -1,9 +1,20 @@
 <?php
-// Edit the configuration below to suit your requirements.
+/**
+ * Edit the configuration below to suit your requirements.
+ *
+ * @author Dale Davies <dale@daledavies.co.uk>
+ * @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,
 ];

jumpapp/index.php

@@ -1,4 +1,11 @@
 <?php
+/**
+ * Initialise the application and generate index page content.
+ *
+ * @author Dale Davies <dale@daledavies.co.uk>
+ * @license MIT
+ */
+
 // Provided by composer for psr-4 style autoloading.
 require __DIR__ .'/vendor/autoload.php';