From 3d475572c6c619e84f6391f4e2f05359454d9f14 Mon Sep 17 00:00:00 2001
From: logmanoriginal <logmanoriginal@users.noreply.github.com>
Date: Thu, 15 Nov 2018 20:27:32 +0100
Subject: [PATCH] [Debug] Improve documentation

---
 lib/Debug.php | 53 +++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 39 insertions(+), 14 deletions(-)

diff --git a/lib/Debug.php b/lib/Debug.php
index 0429f7eb..c467d56d 100644
--- a/lib/Debug.php
+++ b/lib/Debug.php
@@ -1,20 +1,31 @@
 <?php
+/**
+ * This file is part of RSS-Bridge, a PHP project capable of generating RSS and
+ * Atom feeds for websites that don't have one.
+ *
+ * For the full license information, please view the UNLICENSE file distributed
+ * with this source code.
+ *
+ * @package	Core
+ * @license	http://unlicense.org/ UNLICENSE
+ * @link	https://github.com/rss-bridge/rss-bridge
+ */
 
 /**
  * Implements functions for debugging purposes. Debugging can be enabled by
- * placing a file named 'DEBUG' in PATH_ROOT.
+ * placing a file named DEBUG in {@see PATH_ROOT}.
  *
  * The file specifies a whitelist of IP addresses on which debug mode will be
  * enabled. An empty file enables debug mode for everyone (highly discouraged
  * for public servers!). Each line in the file specifies one client in the
  * whitelist. For example:
  *
- * 192.168.1.72
- * 127.0.0.1
- * ::1
+ * * `192.168.1.72`
+ * * `127.0.0.1`
+ * * `::1`
  *
  * Notice: If you are running RSS-Bridge on your local machine, you need to add
- * localhost (either 127.0.0.1 for IPv4 or ::1 for IPv6) to your whitelist!
+ * localhost (either `127.0.0.1` for IPv4 or `::1` for IPv6) to your whitelist!
  *
  * Warning: In debug mode your server may display sensitive information! For
  * security reasons it is recommended to whitelist only specific IP addresses.
@@ -23,18 +34,30 @@ class Debug {
 
 	/**
 	 * Indicates if debug mode is enabled.
-	 * Use Debug::isEnabled() instead of accessing this parameter directly!
+	 *
+	 * Do not access this property directly!
+	 * Use {@see Debug::isEnabled()} instead.
+	 *
+	 * @var bool
 	 */
 	private static $enabled = false;
 
 	/**
-	 * Indicates if debug mode is secure (not enabled for everyone).
-	 * Use Debug::isSecure() instead of accessing this parameter directly!
+	 * Indicates if debug mode is secure.
+	 *
+	 * Do not access this property directly!
+	 * Use {@see Debug::isSecure()} instead.
+	 *
+	 * @var bool
 	 */
 	private static $secure = false;
 
 	/**
-	 * @return bool Indicates if debug mode is enabled
+	 * Returns true if debug mode is enabled
+	 *
+	 * If debug mode is enabled, sets `display_errors = 1` and `error_reporting = E_ALL`
+	 *
+	 * @return bool True if enabled.
 	 */
 	public static function isEnabled() {
 		static $firstCall = true; // Initialized on first call
@@ -63,13 +86,13 @@ class Debug {
 	}
 
 	/**
-	 * Returns true if debug mode has been enabled for specific IP addresses
-	 * only, false otherwise.
+	 * Returns true if debug mode is enabled only for specific IP addresses.
 	 *
-	 * Notice: The security flag is set by Debug::isEnabled(). If this function
-	 * is called before Debug::isEnabled(), the default value is false!
+	 * Notice: The security flag is set by {@see Debug::isEnabled()}. If this
+	 * function is called before {@see Debug::isEnabled()}, the default value is
+	 * false!
 	 *
-	 * @return bool Indicates if debug mode is secure
+	 * @return bool True if debug mode is secure
 	 */
 	public static function isSecure() {
 		return Debug::$secure;
@@ -77,6 +100,8 @@ class Debug {
 
 	/**
 	 * Adds a debug message to error_log if debug mode is enabled
+	 *
+	 * @param string $text The message to add to error_log
 	 */
 	public static function log($text) {
 		if(!Debug::isEnabled()) {