Added inline documentation.

RoboFile.php

@@ -67,7 +67,6 @@ class RoboFile extends \Robo\Tasks {
 	public function makeMustache() {
 		$dir = __DIR__ . '/views/cache';
 		$this->_cleanDir( $dir );
-
 		$mustache = new \Mustache_Engine(
 			array(
 				'loader' => new \Mustache_Loader_FilesystemLoader( __DIR__ . '/views' ),

laps.php

@@ -1,4 +1,5 @@
 <?php
+
 /*
 Plugin Name: Laps
 Plugin URI: https://github.com/Rarst/laps

src/Event/Genesis_Events.php

@@ -20,7 +20,6 @@ class Genesis_Events implements Hook_Event_Config_Interface {
 			return $events;
 		}
 
-
 		$events['genesis_before_header'][10] = [
 			'event'    => 'Header',
 			'category' => 'theme',

src/Event/Hybrid_Events.php

@@ -20,7 +20,6 @@ class Hybrid_Events implements Hook_Event_Config_Interface {
 			return $events;
 		}
 
-
 		$prefix = hybrid_get_prefix();
 
 		$events["{$prefix}_before_header"][10] = [

src/Manager/Asset_Manager.php

@@ -2,14 +2,23 @@
 
 namespace Rarst\Laps\Manager;
 
+/**
+ * Implements load of necessary front–end assets.
+ */
 class Asset_Manager {
 
+	/**
+	 * Sets up the hooks.
+	 */
 	public function __construct() {
 
 		add_action( 'wp_enqueue_scripts', [ $this, 'enqueue_scripts' ] );
 		add_action( 'admin_enqueue_scripts', [ $this, 'enqueue_scripts' ] );
 	}
 
+	/**
+	 * Registers assets and queues as necessary.
+	 */
 	public function enqueue_scripts() {
 
 		$suffix = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';
@@ -21,5 +30,4 @@ class Asset_Manager {
 			wp_enqueue_style( 'laps' );
 		}
 	}
-
 }

src/Manager/Load_Order_Manager.php

@@ -7,6 +7,9 @@ namespace Rarst\Laps\Manager;
  */
 class Load_Order_Manager {
 
+	/**
+	 * Sets up the hooks.
+	 */
 	public function __construct() {
 
 		add_action( 'pre_update_option_active_plugins', [ $this, 'pre_update_option_active_plugins' ] );
@@ -16,7 +19,7 @@ class Load_Order_Manager {
 	/**
 	 * Reorder active plugins so Laps is first and starts timing load early.
 	 *
-	 * @param array $plugins
+	 * @param array $plugins Filtered array of active plugins’ basenames.
 	 *
 	 * @return array
 	 */

src/Manager/Toolbar_Manager.php

@@ -6,11 +6,17 @@ use Rarst\Laps\Record\Recursive_Record_Iterator;
 use Rarst\Laps\Plugin;
 use Rarst\Laps\Record\Timeline_Iterator;
 
+/**
+ * Implements toolbar menu and visualization.
+ */
 class Toolbar_Manager {
 
 	/** @var Plugin $laps */
 	protected $laps;
 
+	/**
+	 * @param Plugin $laps Container instance.
+	 */
 	public function __construct( Plugin $laps ) {
 
 		$this->laps = $laps;
@@ -21,7 +27,7 @@ class Toolbar_Manager {
 	/**
 	 * Render interface and add to the toolbar.
 	 *
-	 * @param \WP_Admin_Bar $wp_admin_bar
+	 * @param \WP_Admin_Bar $wp_admin_bar WordPress core toolbar object.
 	 */
 	public function admin_bar_menu( $wp_admin_bar ) {
 

src/Mustache_Cache_FrozenCache.php

@@ -9,8 +9,8 @@ class Mustache_Cache_FrozenCache extends \Mustache_Cache_FilesystemCache {
 	/**
 	 * Cache and load a compiled Mustache_Template class.
 	 *
-	 * @param string $key
-	 * @param string $value
+	 * @param string $key   Key.
+	 * @param string $value Value.
 	 *
 	 * @return void
 	 */

src/Plugin.php

@@ -14,8 +14,12 @@ use Rarst\Laps\Provider\Record_Provider;
  */
 class Plugin extends Container {
 
+	/** @var array $providers */
 	protected $providers = [];
 
+	/**
+	 * @param array $values Configuration values to apply.
+	 */
 	public function __construct( array $values = [] ) {
 
 		parent::__construct();
@@ -38,6 +42,12 @@ class Plugin extends Container {
 		}
 	}
 
+	/**
+	 * @param ServiceProviderInterface $provider Provider.
+	 * @param array                    $values   Optional configuration.
+	 *
+	 * @return $this|static
+	 */
 	public function register( ServiceProviderInterface $provider, array $values = [] ) {
 
 		$this->providers[] = $provider;

src/Provider/Bootable_Provider_Interface.php

@@ -6,5 +6,10 @@ use Rarst\Laps\Plugin;
 
 interface Bootable_Provider_Interface {
 
+	/**
+	 * @param Plugin $laps Container instance.
+	 *
+	 * @return void
+	 */
 	public function boot( Plugin $laps );
 }

src/Provider/Hook_Event_Provider.php

@@ -10,8 +10,14 @@ use Rarst\Laps\Event\Hybrid_Events;
 use Rarst\Laps\Event\THA_Events;
 use Rarst\Laps\Event\Yoast_Events;
 
+/**
+ * Registers hook event configuration for bundled vendor events.
+ */
 class Hook_Event_Provider implements ServiceProviderInterface {
 
+	/**
+	 * @param Container $pimple Container instance.
+	 */
 	public function register( Container $pimple ) {
 
 		$pimple['hook.events'] = function () {

src/Provider/Manager_Provider.php

@@ -9,8 +9,14 @@ use Rarst\Laps\Manager\Asset_Manager;
 use Rarst\Laps\Manager\Load_Order_Manager;
 use Rarst\Laps\Manager\Toolbar_Manager;
 
+/**
+ * Registers manager classes that implement functionality.
+ */
 class Manager_Provider implements ServiceProviderInterface, Bootable_Provider_Interface {
 
+	/**
+	 * @param Container $pimple Container instance.
+	 */
 	public function register( Container $pimple ) {
 
 		$pimple['managers'] = function ( Plugin $laps ) {
@@ -22,6 +28,9 @@ class Manager_Provider implements ServiceProviderInterface, Bootable_Provider_In
 		};
 	}
 
+	/**
+	 * @param Plugin $laps Container instance.
+	 */
 	public function boot( Plugin $laps ) {
 		$laps['managers'];
 	}

src/Provider/Record_Provider.php

@@ -11,8 +11,14 @@ use Rarst\Laps\Record\Record_Collector_Interface;
 use Rarst\Laps\Record\Sql_Record_Collector;
 use Symfony\Component\Stopwatch\Stopwatch;
 
+/**
+ * Registers record collectors (responsible to gather and compile event data) and their dependencies.
+ */
 class Record_Provider implements ServiceProviderInterface, Bootable_Provider_Interface {
 
+	/**
+	 * @param Container $pimple Container instance.
+	 */
 	public function register( Container $pimple ) {
 
 		$pimple['stopwatch'] = $pimple->factory( function () {
@@ -40,6 +46,9 @@ class Record_Provider implements ServiceProviderInterface, Bootable_Provider_Int
 		};
 	}
 
+	/**
+	 * @param Plugin $laps Container instance.
+	 */
 	public function boot( Plugin $laps ) {
 		$laps['collectors'];
 	}

src/Record/Hook_Record_Collector.php

@@ -6,6 +6,9 @@ use Rarst\Laps\Event\Hook_Event_Config_Interface;
 use Symfony\Component\Stopwatch\Stopwatch;
 use Symfony\Component\Stopwatch\StopwatchEvent;
 
+/**
+ * Processes events based on hooked starts and stops.
+ */
 class Hook_Record_Collector implements Record_Collector_Interface {
 
 	/** @var Hook_Event_Config_Interface[] $event_configs  */
@@ -14,8 +17,13 @@ class Hook_Record_Collector implements Record_Collector_Interface {
 	/** @var Stopwatch $stopwatch */
 	protected $stopwatch;
 
+	/** @var array $events */
 	protected $events = [];
 
+	/**
+	 * @param array     $event_configs Starts and stops configuration.
+	 * @param Stopwatch $stopwatch     Stopwatch instance.
+	 */
 	public function __construct( array $event_configs, Stopwatch $stopwatch ) {
 
 		$this->stopwatch = $stopwatch;
@@ -33,7 +41,7 @@ class Hook_Record_Collector implements Record_Collector_Interface {
 	/**
 	 * Hook events by name and priority from array.
 	 *
-	 * @param array $stops
+	 * @param array $stops Starts and stops to hook.
 	 */
 	public function add_events( $stops ) {
 
@@ -61,7 +69,7 @@ class Hook_Record_Collector implements Record_Collector_Interface {
 	/**
 	 * Mark action for the event on Stopwatch.
 	 *
-	 * @param mixed $input pass through if added to filter
+	 * @param mixed $input Pass through if added to filter.
 	 *
 	 * @return mixed
 	 */
@@ -92,6 +100,9 @@ class Hook_Record_Collector implements Record_Collector_Interface {
 		return $input;
 	}
 
+	/**
+	 * @return Stopwatch_Record[]
+	 */
 	public function get_records() {
 
 		if ( $this->stopwatch->isStarted( 'Toolbar' ) ) {
@@ -109,6 +120,12 @@ class Hook_Record_Collector implements Record_Collector_Interface {
 		return array_map( [ $this, 'transform' ], array_keys( $events ), $events );
 	}
 
+	/**
+	 * @param string         $name  Event name.
+	 * @param StopwatchEvent $event Stopwatch event instance.
+	 *
+	 * @return Stopwatch_Record
+	 */
 	protected function transform( $name, StopwatchEvent $event ) {
 
 		return new Stopwatch_Record( $name, $event );

src/Record/Http_Record_Collector.php

@@ -5,11 +5,17 @@ namespace Rarst\Laps\Record;
 use Symfony\Component\Stopwatch\Stopwatch;
 use Symfony\Component\Stopwatch\StopwatchEvent;
 
+/**
+ * Captures time of network requests made with HTTP API.
+ */
 class Http_Record_Collector implements Record_Collector_Interface {
 
 	/** @var Stopwatch $stopwatch */
 	protected $stopwatch;
 
+	/**
+	 * @param Stopwatch $stopwatch Stopwatch instance.
+	 */
 	public function __construct( Stopwatch $stopwatch ) {
 
 		$this->stopwatch = $stopwatch;
@@ -21,9 +27,9 @@ class Http_Record_Collector implements Record_Collector_Interface {
 	/**
 	 * Capture start time of HTTP request
 	 *
-	 * @param boolean $false
-	 * @param array   $args
-	 * @param string  $url
+	 * @param boolean $false Whether to preempt an HTTP request's return value. Default false.
+	 * @param array   $args  HTTP request arguments.
+	 * @param string  $url   The request URL.
 	 *
 	 * @return boolean
 	 */
@@ -37,13 +43,15 @@ class Http_Record_Collector implements Record_Collector_Interface {
 	/**
 	 * Capture end time of HTTP request
 	 *
-	 * @param array|\WP_Error $response
-	 * @param string          $type
-	 * @param object          $class
-	 * @param array           $args
-	 * @param string          $url
+	 * @param array|\WP_Error $response HTTP response or WP_Error object.
+	 * @param string          $type     Context under which the hook is fired.
+	 * @param object          $class    HTTP transport used.
+	 * @param array           $args     HTTP request arguments.
+	 * @param string          $url      The request URL.
 	 *
 	 * @return mixed
+	 *
+	 * @noinspection MoreThanThreeArgumentsInspection
 	 */
 	public function http_api_debug( $response, $type, $class, $args, $url ) {
 
@@ -52,6 +60,9 @@ class Http_Record_Collector implements Record_Collector_Interface {
 		return $response;
 	}
 
+	/**
+	 * @return Stopwatch_Record[]
+	 */
 	public function get_records() {
 
 		$events = $this->stopwatch->getSectionEvents( '__root__' );
@@ -59,6 +70,12 @@ class Http_Record_Collector implements Record_Collector_Interface {
 		return array_map( [ $this, 'transform' ], array_keys( $events ), $events );
 	}
 
+	/**
+	 * @param string         $name  Event name.
+	 * @param StopwatchEvent $event Stopwatch event instance.
+	 *
+	 * @return Stopwatch_Record
+	 */
 	protected function transform( $name, StopwatchEvent $event ) {
 
 		return new Stopwatch_Record( $name, $event );

src/Record/Recursive_Record_Iterator.php

@@ -2,13 +2,17 @@
 
 namespace Rarst\Laps\Record;
 
+/**
+ * Processes records, recursively bumping overlapping ones to children.
+ */
 class Recursive_Record_Iterator extends \ArrayIterator implements \RecursiveIterator {
 
+	/** @var array $children */
 	protected $children = [];
 
 	/**
-	 * @param Record_Interface[] $records
-	 * @param int                $flags
+	 * @param Record_Interface[] $records Records to process.
+	 * @param int                $flags   Configuration flags.
 	 */
 	public function __construct( array $records, $flags = 0 ) {
 
@@ -29,6 +33,12 @@ class Recursive_Record_Iterator extends \ArrayIterator implements \RecursiveIter
 		parent::__construct( $records, $flags );
 	}
 
+	/**
+	 * @param Record_Interface $record_a Record to compare.
+	 * @param Record_Interface $record_b Record to compare.
+	 *
+	 * @return int
+	 */
 	protected function sort_origin( Record_Interface $record_a, Record_Interface $record_b ) {
 
 		$origin_a = $record_a->get_origin();
@@ -41,11 +51,17 @@ class Recursive_Record_Iterator extends \ArrayIterator implements \RecursiveIter
 		return ( $origin_a < $origin_b ) ? - 1 : 1;
 	}
 
+	/**
+	 * @return bool
+	 */
 	public function hasChildren() {
 
 		return ! empty( $this->children );
 	}
 
+	/**
+	 * @return static
+	 */
 	public function getChildren() {
 
 		return new static( $this->children );

src/Record/Sql_Record.php

@@ -2,6 +2,9 @@
 
 namespace Rarst\Laps\Record;
 
+/**
+ * SQL record of a query event.
+ */
 class Sql_Record implements Record_Interface {
 
 	/** @var string $sql */
@@ -17,10 +20,10 @@ class Sql_Record implements Record_Interface {
 	protected $category;
 
 	/**
-	 * @param string $sql
-	 * @param float  $origin
-	 * @param int    $duration
-	 * @param string $category
+	 * @param string $sql      SQL query.
+	 * @param float  $origin   Start time.
+	 * @param int    $duration Query duration.
+	 * @param string $category Query type.
 	 */
 	public function __construct( $sql, $origin, $duration, $category = 'query-read' ) {
 		$this->sql      = $sql;

src/Record/Sql_Record_Collector.php

@@ -2,10 +2,17 @@
 
 namespace Rarst\Laps\Record;
 
+/**
+ * Processes SQL events from data logged by wpdb.
+ */
 class Sql_Record_Collector implements Record_Collector_Interface {
 
+	/** @var array $query_starts Log of query start times. */
 	protected $query_starts = [];
 
+	/**
+	 * Sets up the query start time log.
+	 */
 	public function __construct() {
 
 		if ( $this->is_savequeries() ) {
@@ -16,7 +23,7 @@ class Sql_Record_Collector implements Record_Collector_Interface {
 	/**
 	 * Capture SQL queries start times
 	 *
-	 * @param string $query
+	 * @param string $query SQL query.
 	 *
 	 * @return string
 	 */
@@ -33,6 +40,9 @@ class Sql_Record_Collector implements Record_Collector_Interface {
 		return $query;
 	}
 
+	/**
+	 * @return Sql_Record[]
+	 */
 	public function get_records() {
 
 		if ( ! $this->is_savequeries() ) {
@@ -62,6 +72,9 @@ class Sql_Record_Collector implements Record_Collector_Interface {
 		return $query_data;
 	}
 
+	/**
+	 * @return bool
+	 */
 	protected function is_savequeries() {
 
 		return defined( 'SAVEQUERIES' ) && SAVEQUERIES;

src/Record/Stopwatch_Record.php

@@ -4,6 +4,9 @@ namespace Rarst\Laps\Record;
 
 use Symfony\Component\Stopwatch\StopwatchEvent;
 
+/**
+ * Record wrapper for an event recorded with Stopwatch.
+ */
 class Stopwatch_Record implements Record_Interface {
 
 	/** @var string $name */

src/Record/Timeline_Iterator.php

@@ -2,6 +2,9 @@
 
 namespace Rarst\Laps\Record;
 
+/**
+ * Processes records into sets for display by template.
+ */
 class Timeline_Iterator implements \Iterator {
 
 	/** @var float $origin Start point for the timeline. */
@@ -16,6 +19,9 @@ class Timeline_Iterator implements \Iterator {
 	/** @var Recursive_Record_Iterator */
 	protected $current;
 
+	/**
+	 * @param Recursive_Record_Iterator $iterator Record iterator.
+	 */
 	public function __construct( Recursive_Record_Iterator $iterator ) {
 
 		global $timestart;
@@ -38,23 +44,40 @@ class Timeline_Iterator implements \Iterator {
 		return $data;
 	}
 
+	/**
+	 * Sets current context to the next set of nested records.
+	 */
 	public function next() {
 		$this->current = $this->current->getChildren();
 	}
 
+	/**
+	 * @return void
+	 */
 	public function key() {
 
 	}
 
+	/**
+	 * @return bool If current set contains records.
+	 */
 	public function valid() {
 		return (bool) count( $this->current );
 	}
 
+	/**
+	 * Rewind to a topmost record set.
+	 */
 	public function rewind() {
 		$this->total   = microtime( true ) * 1000 - $this->origin;
 		$this->current = $this->iterator;
 	}
 
+	/**
+	 * @param Record_Interface $record Record instance.
+	 *
+	 * @return array Record data for display by the template.
+	 */
 	protected function prepare( Record_Interface $record ) {
 
 		$data = [