Tidied up code comments pre-release.

includes/squat-radar-connector.php

@@ -1,11 +1,35 @@
 <?php
+/**
+ * Squat Radar Connector.
+ *
+ * Fetch data from Radar API.
+ *
+ * @package squat-radar
+ * @since 2.0.0
+ */
 
+// Exit if accessed directly.
+defined( 'ABSPATH' ) || exit;
 
 class Squat_Radar_Connector {
 
 	const BASE_URL = 'https://radar.squat.net';
 	const API_EVENTS = '/api/1.2/search/events.json';
 
+	/**
+	 * Retrieve array of events from API based on a query.
+	 *
+	 * @see self::encode_api_query() for $query values.
+	 *
+	 * @param array $query
+	 *  Key value pairs for the API query.
+	 * 
+	 * @return array
+	 *  Array of events.
+	 *
+	 * @throws Squat_Radar_Connector_Exception
+	 *  When events are not returned, but a timeout or API error.
+	 */
 	function get_events( $query ) {
 
 		$url = self::BASE_URL . self::API_EVENTS . '?' . build_query( $query );
@@ -21,6 +45,15 @@ class Squat_Radar_Connector {
 
 	}
 
+	/**
+	 * Turn a Radar frontend Search URL into facets key value and language values.
+	 *
+	 * @param string $url
+	 *  The https://radar.squat.net/events filtered URL.
+	 *
+	 * @return array
+	 *  [ 'language' => language code, 'facets' => [key => value] ].
+	 */
 	function decode_search_url( $url ) {
 		$matches = [];
 		$result = [];
@@ -36,6 +69,21 @@ class Squat_Radar_Connector {
 		return $result;
 	}
 
+	/**
+	 * Encode a query key value from facets, fields, language, limit.
+	 *
+	 * @param array $facets
+	 *  Optional. Facet key => filter value array.
+	 * @param array $fields
+	 *  Optional. Index array of API field names to retrieve.
+	 * @param string $language
+	 *  Optional. Language code.
+	 * @param int $limit
+	 *  Optional. Maximum number to items to return.
+	 *
+	 * @return array
+	 *  Array for use in self::get_events().
+	 */
 	function encode_api_query( $facets = [], $fields = [], $language = '', $limit = 10 ) {
 		$query = [];
 
@@ -57,6 +105,25 @@ class Squat_Radar_Connector {
 		return $query;
 	}
 
+	/**
+	 * Return events meeting argument criteria. Either from cache, or retrieved from API.
+	 *
+	 * @param array $facets
+	 *  Facet name key => filter value.
+	 * @param array $fields
+	 *  Optional. Array of key names.
+	 * @param string $language
+	 *  Optional. Language code.
+	 * @param int $limit
+	 *  Maximum number of items to return.
+	 * @param int $expiration
+	 *  Seconds to cache results. 0 never expires.
+	 * @param bool $reset
+	 *  Force a cache reset.
+	 *
+	 * @return array
+	 *  Array of event arrays, values keyed by field name.
+	 */
 	function events( $facets, $fields = [], $language = NULL, $limit = 10, $expiration = 10800, $reset = FALSE ) {
 		// Fields we often want to get data out of but not necessarily are chosen to be shown.
 		$fields = array_merge($fields, ['uuid', 'title', 'body:value', 'url', 'event_status']);

includes/squat-radar-formatter.php

@@ -1,7 +1,27 @@
 <?php
+/**
+ * Squat Radar Events Formatter.
+ *
+ * Provides filters to format the output of Squat Radar Events.
+ *
+ * 'squat_radar_format_event' allows the whole event to be formatted.
+ * Default filter Squat_Radar_Formatter::format_event().
+ *
+ * 'squat_radar_field_html' formats individual fields.
+ * Basic implementation Squat_Radar_Formatter::field_html().
+ *
+ * @package squat-radar
+ * @since 2.0.0
+ */
+
+// Exit if accessed directly.
+defined( 'ABSPATH' ) || exit;
 
 class Squat_Radar_Formatter {
 
+	/**
+	 * Register filters with Wordpress.
+	 */
 	static public function register() {
 		// Filter to go through fields and then call filters to turn these into HTML.
 		add_filter('squat_radar_format_event', [__CLASS__, 'format_event'], 10, 3);
@@ -28,6 +48,20 @@ class Squat_Radar_Formatter {
 		add_filter('squat_radar_field_html', [__CLASS__, 'field_title_html'], 15, 4);
 	}
 
+	/**
+	 * Implementation of 'squat_radar_format_event'.
+	 *
+	 * Formats an API event array into HTML.
+	 *
+	 * @param array $event
+	 *  The event array from the API. Nested field names with values.
+	 * @param array $fields
+	 *  The field names required for display. Colons used to denote nesting.
+	 * @param array $context
+	 *
+	 * @return string
+	 *  HTML.
+	 */
 	static public function format_event($event, $fields, $context) {
 
 		$context['event'] = $event;
@@ -45,6 +79,74 @@ class Squat_Radar_Formatter {
 
 	}
 
+	/**
+	 * Basic implementation of 'squat_radar_field_html' filter.
+	 *
+	 * Put the output into HTML.
+	 *
+	 * @param array|string $value
+	 *   The field value being manipulated to become HTML to be displayed.
+	 * @param array|string $original
+	 *   The original value of the field before any changes by filters.
+	 * @param array $field
+	 *   The field tree. $field[0] being the name of the present field. $field[1]
+	 *   being any parent etc.
+	 * @param array $context
+	 *
+	 * @return string
+	 *   Flattend array with additional default classes.
+	 */
+	static public function field_html($value, $original, $field, $context) {
+		if ($value != $original) {
+			return $value;
+		}
+
+		if (is_array($value)) {
+			if ( ! empty($value['value']) ) {
+				$value = $value['value'];
+			}
+			elseif ( ! empty($value['title']) ) {
+				$value = $value['title'];
+			}
+			elseif ( ! empty($value['name']) ) {
+				$value = $value['name'];
+			}
+			elseif ( ! empty($value[0]['value']) ) {
+				foreach ($value as $row) {
+					$values[] = $row['value'];
+				}
+				$value = $values;
+			}
+			elseif ( ! empty($value[0]['title']) ) {
+				foreach ($value as $row) {
+					$titles[] = $row['title'];
+				}
+				$value = $titles;
+			}
+			elseif ( ! empty($value[0]['name']) ) {
+				foreach ($value as $row) {
+					$names[] = $row['name'];
+				}
+				$value = $names;
+			}
+		}
+
+		if (is_array($value)) {
+			$output = '<ul class="squat-radar-' . sanitize_html_class($field[0]) . ' squat-radar-list">';
+			foreach ($value as $row) {
+				$output .= '<li class="squat-radar-item-' . sanitize_html_class($field[0]) . '">' . sanitize_text_field( $row ) . '</li>';
+			}
+			$output .= '</ul>';
+
+			return $output;
+		}
+		else {
+			$value = '<span class="squat-radar-' . sanitize_html_class($field[0]) . '">' . wp_kses_post( $value ) . '</span>';
+		}
+
+		return $value;
+	}
+		
 	/**
 	 * Date field formatting implementation of 'squat_radar_field_html' filter.
 	 */
@@ -257,11 +359,10 @@ class Squat_Radar_Formatter {
 		return $value;
 	}
 
-
 	/**
 	 * Format image implementation of 'squat_radar_field_html' filter.
 	 *
-	 * Deliberatly run after field_link_html. Showing how to override an existing filter.
+	 * Intentionally run after field_link_html. Showing how to override an existing filter.
 	 * image:file:url
 	 */
 	static public function field_image_html($value, $original, $field, $context) {
@@ -272,76 +373,9 @@ class Squat_Radar_Formatter {
 	    	return $value;
 	}
 
-	/**
-	 * Basic implementation of 'squat_radar_field_html' filter.
-	 *
-	 * Put the output into HTML.
-	 *
-	 * @param array|string $value
-	 *   The field value being manipulated to become HTML to be displayed.
-	 * @param array|string $original
-	 *   The original value of the field before any changes by filters.
-	 * @param array $field
-	 *   The field tree. $field[0] being the name of the present field. $field[1]
-	 *   being any parent etc.
-	 * @param array $context
-	 *
-	 * @return string
-	 *   Flattend array with additional default classes.
-	 */
-	static public function field_html($value, $original, $field, $context) {
-		if ($value != $original) {
-			return $value;
-		}
-
-		if (is_array($value)) {
-			if ( ! empty($value['value']) ) {
-				$value = $value['value'];
-			}
-			elseif ( ! empty($value['title']) ) {
-				$value = $value['title'];
-			}
-			elseif ( ! empty($value['name']) ) {
-				$value = $value['name'];
-			}
-			elseif ( ! empty($value[0]['value']) ) {
-				foreach ($value as $row) {
-					$values[] = $row['value'];
-				}
-				$value = $values;
-			}
-			elseif ( ! empty($value[0]['title']) ) {
-				foreach ($value as $row) {
-					$titles[] = $row['title'];
-				}
-				$value = $titles;
-			}
-			elseif ( ! empty($value[0]['name']) ) {
-				foreach ($value as $row) {
-					$names[] = $row['name'];
-				}
-				$value = $names;
-			}
-		}
-
-		if (is_array($value)) {
-			$output = '<ul class="squat-radar-' . sanitize_html_class($field[0]) . ' squat-radar-list">';
-			foreach ($value as $row) {
-				$output .= '<li class="squat-radar-item-' . sanitize_html_class($field[0]) . '">' . sanitize_text_field( $row ) . '</li>';
-			}
-			$output .= '</ul>';
-
-			return $output;
-		}
-		else {
-			$value = '<span class="squat-radar-' . sanitize_html_class($field[0]) . '">' . wp_kses_post( $value ) . '</span>';
-		}
-
-		return $value;
-	}
 
 	/**
- 	 * Title field HTML implentation of 'squat_radar_field_html' filter.
+ 	 * Title field HTML implementation of 'squat_radar_field_html' filter.
 	 */
 	static public function field_title_html($value, $original, $field, $context) {
 		if (($field[0] == 'title' || $field[0] == 'title_field') && count($field) == 1) {

includes/squat-radar-instance.php

@@ -1,11 +1,12 @@
 <?php
-
 /**
  * Manage the Squat Radar plugin.
  *
- * @package Squat_Radar
+ * @package squat-radar
+ * @since 2.0.0
  */
 
+// Exit if accessed directly.
 defined( 'ABSPATH' ) || exit;
 
 /**
@@ -38,14 +39,15 @@ class Squat_Radar_Instance {
 	}
 
 	/**
-	 * Load translation files
+	 * Load translation files.
-	 *
-	 * @since 0.2.4
 	 */
 	function i18n() {
 		load_plugin_textdomain( 'squat-radar', false, '/languages' );
 	}
 
+	/**
+	 * Shortcode callback to print the dynamic sidebar.
+	 */
 	function print_sidebar() {
 		ob_start();
 
@@ -56,8 +58,9 @@ class Squat_Radar_Instance {
 		return ob_get_clean();
 	}
 
-
+	/**
-
+	 * Action callback to add the dynamic sidebar.
+	 */
 	function add_sidebar() {
 
 		register_sidebar([

includes/squat-radar-widget.php

@@ -1,5 +1,13 @@
 <?php
+/**
+ * Squat Radar Events Widget.
+ *
+ * @package squat-radar
+ * @since 2.0.0
+ */
 
+// Exit if accessed directly.
+defined( 'ABSPATH' ) || exit;
 
 class Squat_Radar_Widget extends WP_Widget {
 
@@ -28,15 +36,26 @@ class Squat_Radar_Widget extends WP_Widget {
 		add_option( 'squat_radar_widget_cron_run', []);
 	}
 
+	/**
+	 * Enqueue scripts callback, add CSS.
+	 */
 	static public function widget_style() {
 		wp_register_style( 'squat-radar-widget',  SQUAT_RADAR_URL . '/assets/squat-radar.css' );
 		wp_enqueue_style( 'squat-radar-widget' );
 	}
 
+	/**
+	 * Enqueue scripts callback, add JS.
+	 */
 	static public function widget_script() {
     		wp_register_script( 'squat-radar-widget',  SQUAT_RADAR_URL . '/assets/squat-radar.js', ['jquery'] );
 	}
 
+	/**
+	 * Cron action.
+	 *
+	 * Uses an option to keep track of when run, and updates any (experimental) widgets that update using a cron period instead of ajax.
+	 */
 	public static function cache_cron() {
 		$now = time();
 		$last_run = get_option('squat_radar_widget_cron_run', []);
@@ -50,6 +69,9 @@ class Squat_Radar_Widget extends WP_Widget {
 		set_option('squat_radar_widget_cron_run', $last_run);
 	}
 
+	/**
+	 * Refresh an individual widget instance for cache_cron().
+	 */
 	protected static function cache_refresh($instance) {
 		$connector = new Squat_Radar_Connector();
 
@@ -58,6 +80,7 @@ class Squat_Radar_Widget extends WP_Widget {
 		$languages = array_merge($instance['url']['keys']['language'], (array) $languages);
 		foreach ($languages as $language) {
 			try {
+				// Force update. Don't set expire.
 				$data = $connector->events($instance['url']['keys']['facets'], $instance['fields'], $language, $instance['limit'], 0, TRUE );
 			}
 			catch ( Squat_Radar_Connector_Exception $e ) {
@@ -68,7 +91,11 @@ class Squat_Radar_Widget extends WP_Widget {
 		return TRUE;
 	}
 
-
+	/**
+	 * Implementation of WP_Widget::widget().
+	 *
+	 * Outputs the events for the correct instance of the widget.
+	 */
 	public function widget( $args, $instance ) {
 		$widget_id = 'squat_radar_widget_' . $this->number; 
 		
@@ -104,6 +131,9 @@ class Squat_Radar_Widget extends WP_Widget {
 		echo $args['after_widget'];
 	}
 
+	/**
+	 * Action callback for AJAX widget display.
+	 */
 	public static function ajax_callback() {
 		if ( ! array_key_exists('instance', $_POST) ) {
 			wp_die();
@@ -138,6 +168,11 @@ class Squat_Radar_Widget extends WP_Widget {
 		return $html;
 	}
 
+	/**
+	 * Implementation of WP_Widget::form().
+	 *
+	 * Widget options.
+	 */
 	public function form( $instance ) {
 
 		//
@@ -269,7 +304,11 @@ class Squat_Radar_Widget extends WP_Widget {
 
 	}
 
-
+	/**
+	 * Implementation of WP_Widget::update().
+	 *
+	 * Save widget options.
+	 */
 	public function update( $new_instance, $old_instance ) {
 		$options = [];