lib: Add API documentation

lib/BridgeCard.php

@@ -1,6 +1,33 @@
 <?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
+ */
+
+/**
+ * A generator class for a single bridge card on the home page of RSS-Bridge.
+ *
+ * This class generates the HTML content for a single bridge card for the home
+ * page of RSS-Bridge.
+ *
+ * @todo Return error if a caller creates an object of this class.
+ * @todo Use self:: instead of BridgeCard:: in this class
+ */
 final class BridgeCard {
 
+	/**
+	 * Build a HTML document string of buttons for each of the provided formats
+	 *
+	 * @param array $formats A list of format names
+	 * @return string The document string
+	 */
 	private static function buildFormatButtons($formats) {
 		$buttons = '';
 
@@ -16,6 +43,13 @@ final class BridgeCard {
 		return $buttons;
 	}
 
+	/**
+	 * Get the form header for a bridge card
+	 *
+	 * @param string $bridgeName The bridge name
+	 * @param bool $isHttps If disabled, adds a warning to the form
+	 * @return string The form header
+	 */
 	private static function getFormHeader($bridgeName, $isHttps = false) {
 		$form = <<<EOD
 			<form method="GET" action="?">
@@ -31,6 +65,17 @@ This bridge is not fetching its content through a secure connection</div>';
 		return $form;
 	}
 
+	/**
+	 * Get the form body for a bridge
+	 *
+	 * @param string $bridgeName The bridge name
+	 * @param array $formats A list of supported formats
+	 * @param bool $isActive Indicates if a bridge is enabled or not
+	 * @param bool $isHttps Indicates if a bridge uses HTTPS or not
+	 * @param string $parameterName Sets the bridge context for the current form
+	 * @param array $parameters The bridge parameters
+	 * @return string The form body
+	 */
 	private static function getForm($bridgeName,
 	$formats,
 	$isActive = false,
@@ -88,6 +133,12 @@ This bridge is not fetching its content through a secure connection</div>';
 		return $form . '</form>' . PHP_EOL;
 	}
 
+	/**
+	 * Get input field attributes
+	 *
+	 * @param array $entry The current entry
+	 * @return string The input field attributes
+	 */
 	private static function getInputAttributes($entry) {
 		$retVal = '';
 
@@ -103,6 +154,14 @@ This bridge is not fetching its content through a secure connection</div>';
 		return $retVal;
 	}
 
+	/**
+	 * Get text input
+	 *
+	 * @param array $entry The current entry
+	 * @param string $id The field ID
+	 * @param string $name The field name
+	 * @return string The text input field
+	 */
 	private static function getTextInput($entry, $id, $name) {
 		return '<input '
 		. BridgeCard::getInputAttributes($entry)
@@ -118,6 +177,14 @@ This bridge is not fetching its content through a secure connection</div>';
 		. PHP_EOL;
 	}
 
+	/**
+	 * Get number input
+	 *
+	 * @param array $entry The current entry
+	 * @param string $id The field ID
+	 * @param string $name The field name
+	 * @return string The number input field
+	 */
 	private static function getNumberInput($entry, $id, $name) {
 		return '<input '
 		. BridgeCard::getInputAttributes($entry)
@@ -133,6 +200,14 @@ This bridge is not fetching its content through a secure connection</div>';
 		. PHP_EOL;
 	}
 
+	/**
+	 * Get list input
+	 *
+	 * @param array $entry The current entry
+	 * @param string $id The field ID
+	 * @param string $name The field name
+	 * @return string The list input field
+	 */
 	private static function getListInput($entry, $id, $name) {
 		$list = '<select '
 		. BridgeCard::getInputAttributes($entry)
@@ -185,6 +260,14 @@ This bridge is not fetching its content through a secure connection</div>';
 		return $list;
 	}
 
+	/**
+	 * Get checkbox input
+	 *
+	 * @param array $entry The current entry
+	 * @param string $id The field ID
+	 * @param string $name The field name
+	 * @return string The checkbox input field
+	 */
 	private static function getCheckboxInput($entry, $id, $name) {
 		return '<input '
 		. BridgeCard::getInputAttributes($entry)
@@ -198,6 +281,14 @@ This bridge is not fetching its content through a secure connection</div>';
 		. PHP_EOL;
 	}
 
+	/**
+	 * Gets a single bridge card
+	 *
+	 * @param string $bridgeName The bridge name
+	 * @param array $formats A list of formats
+	 * @param bool $isActive Indicates if the bridge is active or not
+	 * @return string The bridge card
+	 */
 	static function displayBridgeCard($bridgeName, $formats, $isActive = true){
 
 		$bridge = Bridge::create($bridgeName);