Minor code cleanup: PHPDoc, spelling, unused variables, etc.

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Release archives now have the same structure as GitHub-generated archives:
     - archives contain a `Shaarli` directory, itself containing sources + dependencies
     - the tarball is now gzipped
+- Minor code cleanup: PHPDoc, spelling, unused variables, etc.
 
 ### Fixed
 - Fix the server `<self>` value in Atom/RSS feeds

application/ApplicationUtils.php

@@ -15,6 +15,9 @@ class ApplicationUtils
      *
      * The code is read from the raw content of the version file on the Git server.
      *
+     * @param string $url     URL to reach to get the latest version.
+     * @param int    $timeout Timeout to check the URL (in seconds).
+     *
      * @return mixed the version code from the repository if available, else 'false'
      */
     public static function getLatestGitVersionCode($url, $timeout=2)
@@ -49,6 +52,7 @@ public static function getLatestGitVersionCode($url, $timeout=2)
      * @param int    $checkInterval  the minimum interval between update checks (in seconds
      * @param bool   $enableCheck    whether to check for new versions
      * @param bool   $isLoggedIn     whether the user is logged in
+     * @param string $branch         check update for the given branch
      *
      * @throws Exception an invalid branch has been set for update checks
      *
@@ -152,7 +156,7 @@ public static function checkResourcePermissions($conf)
             }
         }
 
-        // Check cache and data directories are readable and writeable
+        // Check cache and data directories are readable and writable
         foreach (array(
             $conf->get('resource.thumbnails_cache'),
             $conf->get('resource.data_dir'),
@@ -167,7 +171,7 @@ public static function checkResourcePermissions($conf)
             }
         }
 
-        // Check configuration files are readable and writeable
+        // Check configuration files are readable and writable
         foreach (array(
             $conf->getConfigFileExt(),
             $conf->get('resource.datastore'),

application/CachedPage.php

@@ -35,7 +35,7 @@ public function __construct($cacheDir, $url, $shouldBeCached)
     /**
      * Returns the cached version of a page, if it exists and should be cached
      *
-     * @return a cached version of the page if it exists, null otherwise
+     * @return string a cached version of the page if it exists, null otherwise
      */
     public function cachedVersion()
     {

application/LinkUtils.php

@@ -81,7 +81,7 @@ function html_extract_charset($html)
 /**
  * Count private links in given linklist.
  *
- * @param array $links Linklist.
+ * @param array|Countable $links Linklist.
  *
  * @return int Number of private links.
  */
@@ -162,6 +162,7 @@ function space2nbsp($text)
  *
  * @param string $description shaare's description.
  * @param string $redirector  if a redirector is set, use it to gerenate links.
+ * @param string $indexUrl    URL to Shaarli's index.
  *
  * @return string formatted description.
  */

application/NetscapeBookmarkUtils.php

@@ -86,7 +86,7 @@ private static function importStatus(
      * Imports Web bookmarks from an uploaded Netscape bookmark dump
      *
      * @param array  $post      Server $_POST parameters
-     * @param array  $file      Server $_FILES parameters
+     * @param array  $files     Server $_FILES parameters
      * @param LinkDB $linkDb    Loaded LinkDB instance
      * @param string $pagecache Page cache
      *

application/TimeZone.php

@@ -7,9 +7,9 @@
  * Example: preselect Europe/Paris
  *  list($htmlform, $js) = generateTimeZoneForm('Europe/Paris');
  *
- * @param string $preselected_timezone preselected timezone (optional)
+ * @param string $preselectedTimezone preselected timezone (optional)
  *
- * @return an array containing the generated HTML form and Javascript code
+ * @return array containing the generated HTML form and Javascript code
  **/
 function generateTimeZoneForm($preselectedTimezone='')
 {
@@ -27,10 +27,6 @@ function generateTimeZoneForm($preselectedTimezone='')
         $pcity = substr($preselectedTimezone, $spos+1);
     }
 
-    // Display config form:
-    $timezoneForm = '';
-    $timezoneJs = '';
-
     // The list is in the form 'Europe/Paris', 'America/Argentina/Buenos_Aires'
     // We split the list in continents/cities.
     $continents = array();
@@ -97,7 +93,7 @@ function generateTimeZoneForm($preselectedTimezone='')
  * @param string $continent the timezone continent
  * @param string $city      the timezone city
  *
- * @return whether continent/city is a valid timezone
+ * @return bool whether continent/city is a valid timezone
  */
 function isTimeZoneValid($continent, $city)
 {

application/Updater.php

@@ -37,7 +37,7 @@ class Updater
      *
      * @param array         $doneUpdates Updates which are already done.
      * @param LinkDB        $linkDB      LinkDB instance.
-     * @oaram ConfigManager $conf        Configuration Manager instance.
+     * @param ConfigManager $conf        Configuration Manager instance.
      * @param boolean       $isLoggedIn  True if the user is logged in.
      */
     public function __construct($doneUpdates, $linkDB, $conf, $isLoggedIn)

application/Url.php

@@ -62,21 +62,7 @@ function add_trailing_slash($url)
 {
     return $url . (!endsWith($url, '/') ? '/' : '');
 }
-/**
- * Converts an URL with an IDN host to a ASCII one.
- *
- * @param string $url Input URL.
- *
- * @return string converted URL.
- */
-function url_with_idn_to_ascii($url)
-{
-    $parts = parse_url($url);
-    $parts['host'] = idn_to_ascii($parts['host']);
 
-    $httpUrl = new \http\Url($parts);
-    return $httpUrl->toString();
-}
 /**
  * URL representation and cleanup utilities
  *

application/Utils.php

@@ -32,6 +32,10 @@ function logm($logFile, $clientIp, $message)
  *
  *  In Shaarli, they are used as a tinyurl-like link to individual entries,
  *  e.g. smallHash('20111006_131924') --> yZH23w
+ *
+ * @param string $text Create a hash from this text.
+ *
+ * @return string generated small hash.
  */
 function smallHash($text)
 {
@@ -106,7 +110,9 @@ function unescape($str)
 }
 
 /**
- * Link sanitization before templating
+ * Sanitize link before rendering.
+ *
+ * @param array $link Link to escape.
  */
 function sanitizeLink(&$link)
 {

application/config/ConfigJson.php

@@ -21,7 +21,7 @@ function read($filepath)
         $data = json_decode($data, true);
         if ($data === null) {
             $error = json_last_error();
-            throw new Exception('An error occured while parsing JSON file: error code #'. $error);
+            throw new Exception('An error occurred while parsing JSON file: error code #'. $error);
         }
         return $data;
     }

application/config/ConfigManager.php

@@ -37,6 +37,8 @@ class ConfigManager
 
     /**
      * Constructor.
+     *
+     * @param string $configFile Configuration file path without extension.
      */
     public function __construct($configFile = 'data/config')
     {

index.php

@@ -606,8 +606,6 @@ function showDailyRSS($conf) {
         $absurl = escape(index_url($_SERVER).'?do=daily&day='.$day);  // Absolute URL of the corresponding "Daily" page.
 
         // Build the HTML body of this RSS entry.
-        $html = '';
-        $href = '';
         $links = array();
 
         // We pre-format some fields for proper output.
@@ -833,7 +831,7 @@ function renderPage($conf, $pluginManager)
         // Get only links which have a thumbnail.
         foreach($links as $link)
         {
-            $permalink='?'.escape(smallhash($link['linkdate']));
+            $permalink='?'.escape(smallHash($link['linkdate']));
             $thumb=lazyThumbnail($conf, $link['url'],$permalink);
             if ($thumb!='') // Only output links which have a thumbnail.
             {
@@ -867,7 +865,7 @@ function renderPage($conf, $pluginManager)
             $maxcount = max($maxcount, $value);
         }
 
-        // Sort tags alphabetically: case insensitive, support locale if avalaible.
+        // Sort tags alphabetically: case insensitive, support locale if available.
         uksort($tags, function($a, $b) {
             // Collator is part of PHP intl.
             if (class_exists('Collator')) {
@@ -1670,8 +1668,6 @@ function buildLinkList($PAGE,$LINKSDB, $conf, $pluginManager)
         $next_page_url = '?page=' . ($page-1) . $searchtermUrl . $searchtagsUrl;
     }
 
-    $token = isLoggedIn() ? getToken($conf) : '';
-
     // Fill all template fields.
     $data = array(
         'previous_page_url' => $previous_page_url,

tests/config/ConfigJsonTest.php

@@ -41,7 +41,7 @@ public function testReadNonExistent()
      * Read a non existent config file -> empty array.
      *
      * @expectedException Exception
-     * @expectedExceptionMessage An error occured while parsing JSON file: error code #4
+     * @expectedExceptionMessage An error occurred while parsing JSON file: error code #4
      */
     public function testReadInvalidJson()
     {