lib: Add API documentation

lib/Authentication.php

@@ -1,6 +1,48 @@
 <?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
+ */
+
+/**
+ * Authentication module for RSS-Bridge.
+ *
+ * This class implements an authentication module for RSS-Bridge, utilizing the
+ * HTTP authentication capabilities of PHP.
+ *
+ * _Notice_: Authentication via HTTP does not prevent users from accessing files
+ * on your server. If your server supports `.htaccess`, you should globally restrict
+ * access to files instead.
+ *
+ * @link https://php.net/manual/en/features.http-auth.php HTTP authentication with PHP
+ * @link https://httpd.apache.org/docs/2.4/howto/htaccess.html Apache HTTP Server
+ * Tutorial: .htaccess files
+ *
+ * @todo This class should respond with an error when creating an object from it.
+ * See {@see Bridge}, {@see Cache} or {@see Format} for reference.
+ * @todo Configuration parameters should be stored internally instead of accessing
+ * the configuration class directly.
+ * @todo Add functions to detect if a user is authenticated or not. This can be
+ * utilized for limiting access to authorized users only.
+ */
 class Authentication {
 
+	/**
+	 * Requests the user for login credentials if necessary.
+	 *
+	 * Responds to an authentication request or returns the `WWW-Authenticate`
+	 * header if authentication is enabled in the configuration of RSS-Bridge
+	 * (`[authentication] enable = true`).
+	 *
+	 * @return void
+	 */
 	public static function showPromptIfNeeded() {
 
 		if(Configuration::getConfig('authentication', 'enable') === true) {
@@ -13,6 +55,13 @@ class Authentication {
 
 	}
 
+	/**
+	 * Verifies if an authentication request was received and compares the
+	 * provided username and password to the configuration of RSS-Bridge
+	 * (`[authentication] username` and `[authentication] password`).
+	 *
+	 * @return bool True if authentication succeeded.
+	 */
 	public static function verifyPrompt() {
 
 		if(isset($_SERVER['PHP_AUTH_USER']) && isset($_SERVER['PHP_AUTH_PW'])) {