Fix grammar, improve clarity, and standardize phrasing in docs and code.

This addresses issues detected by PhpStorm.

Author: westonruter

plugins/optimization-detective/docs/hooks.md

@@ -9,7 +9,7 @@
 Fires when the Optimization Detective is initializing.
 
 This action is useful for loading extension code that depends on Optimization Detective to be running. The version
-of the plugin is passed as the sole argument so that if the required version is not present, the callback can short circuit.
+of the plugin is passed as the sole argument so that if the required version is not present, the callback can short-circuit.
 
 Example:
 
@@ -115,7 +115,7 @@ It is important to note that this action fires _after_ the entire template has b
 other words, it will fire after the `wp_footer` action.
 
 This action runs before any of the registered tag visitors have been invoked in the current response. It is useful for
-an extension to gather the required information from the currently-stored URL Metrics for tag visitors to later leverage.
+an extension to gather the required information from the currently stored URL Metrics for tag visitors to later leverage.
 See [example](https://github.com/WordPress/performance/pull/1921) from the Image Prioritizer plugin where it can be used
 to determine what the common external LCP background-image is for each viewport group up front so that this doesn't have
 to be computed when a tag visitor is invoked.
@@ -187,10 +187,10 @@ The additional attribution data is made available to client-side extension scrip
 Filters the breakpoint max widths to group URL Metrics for various viewports. 
 
 Each number represents the maximum width (inclusive) for a given breakpoint. So if there is one number, 480, then this means there will be two viewport groupings, one for 0\<=480, and another \>480. If instead there are the two breakpoints defined, 480 and 782, then this means there will be three viewport groups of URL Metrics, one for 0\<=480 (i.e. mobile), another 481\<=782 (i.e. phablet/tablet), and another \>782 (i.e. desktop).
-This array may be empty in which case there are no responsive breakpoints and all URL Metrics are collected in a single group.
+This array may be empty, in which case there are no responsive breakpoints, and all URL Metrics are collected in a single group.
 A breakpoint must be greater than zero or else a usage warning will occur.
 
-These default breakpoints are reused from Gutenberg which appear to be used the most in media queries that affect frontend styles.
+These default breakpoints are reused from Gutenberg, which appear to be used the most in media queries that affect frontend styles.
 
 ### Filter: `od_can_optimize_response` (default: boolean condition, see below)
 
@@ -217,16 +217,16 @@ add_filter( 'od_can_optimize_response', function( $can_optimize, array $disabled
 }, 10, 2 );
 ```
 
-Note that some conditions cannot be overridden by this filter. Even if the filter returns `true`, optimization will still be disabled when:
+Note that this filter cannot override some conditions. Even if the filter returns `true`, optimization will still be disabled when:
 
 1. The REST API for storing URL Metrics is not available.
-2. The URL has the `optimization_detective_disabled` query parameter.
+2. The URL has the `optimization_detective_disabled` query parameter.
 
 ### Filter: `od_url_metrics_breakpoint_sample_size` (default: 3)
 
 Filters the sample size for a breakpoint's URL Metrics on a given URL. 
 
-The filtered value must be greater than zero; otherwise it will be ignored and a usage warning will result.
+The filtered value must be greater than zero; otherwise it will be ignored, and a usage warning will result.
 
 You can increase the sample size if you want better guarantees that the applied optimizations will be accurate. During development, it may be helpful to reduce the sample size to 1 (along with setting the `od_url_metric_storage_lock_ttl` and `od_url_metric_freshness_ttl` filters below) so that you don't have to keep reloading the page to collect new URL Metrics to flush out stale ones during active development:
 
@@ -240,7 +240,7 @@ add_filter( 'od_url_metrics_breakpoint_sample_size', function (): int {
 
 Filters how long the current IP is locked from submitting another URL metric storage REST API request.
 
-Filtering the TTL to zero will disable any URL Metric storage locking. This is useful, for example, to disable locking when a user is logged-in with code like the following:
+Filtering the TTL to zero will disable any URL Metric storage locking. This is useful, for example, to disable locking when a user is logged in with code like the following:
 
 ```php
 add_filter( 'od_metrics_storage_lock_ttl', function ( int $ttl ): int {
@@ -250,7 +250,7 @@ add_filter( 'od_metrics_storage_lock_ttl', function ( int $ttl ): int {
 
 By default, the TTL is zero (0) for authorized users and sixty (60) for everyone else. Whether the current user is authorized is determined by whether the user has the `od_store_url_metric_now` capability. This custom capability by default maps to the `manage_options` primitive capability via the `user_has_cap` filter.
 
-During development this is useful to set to zero so you can quickly collect new URL Metrics by reloading the page without having to wait for the storage lock to release:
+During development this is useful to set to zero, so you can quickly collect new URL Metrics by reloading the page without having to wait for the storage lock to release:
 
 ```php
 add_filter( 'od_metrics_storage_lock_ttl', function ( int $ttl ): int {
@@ -288,7 +288,7 @@ add_filter( 'od_url_metric_freshness_ttl', '__return_zero' );
 
 Filters the minimum allowed viewport aspect ratio for URL Metrics.
 
-The 0.4 value is intended to accommodate the phone with the greatest known aspect ratio at 21:9 when rotated 90 degrees to 9:21 (0.429). During development when you have the DevTools console open on the right, the viewport aspect ratio will be smaller than normal. In this case, you may want to set this to 0:
+The 0.4 value is intended to accommodate the phone with the greatest known aspect ratio at 21:9 when rotated 90 degrees to 9:21 (0.429). During development, when you have the DevTools console open on the right, the viewport aspect ratio will be smaller than normal. In this case, you may want to set this to 0:
 
 ```php
 add_filter( 'od_minimum_viewport_aspect_ratio', static function (): int {
@@ -312,13 +312,15 @@ add_filter( 'od_maximum_viewport_aspect_ratio', static function (): int {
 
 ### Filter: `od_template_output_buffer` (default: the HTML response)
 
-Filters the template output buffer prior to sending to the client. This filter is added to implement [\#43258](https://core.trac.wordpress.org/ticket/43258) in WordPress core.
+Filters the template output buffer before sending it to the client. 
+
+This filter is added to implement [\#43258](https://core.trac.wordpress.org/ticket/43258) in WordPress core.
 
 ### Filter: `od_url_metric_schema_element_item_additional_properties` (default: empty array)
 
 Filters additional schema properties which should be allowed for an element's item in a URL Metric.
 
-For example to add a `resizedBoundingClientRect` property:
+For example, to add a `resizedBoundingClientRect` property:
 
 ```php
 <?php
@@ -410,7 +412,7 @@ add_filter( 'od_url_metric_garbage_collection_ttl', '__return_zero' );
 
 Filters the maximum allowed size in bytes for a URL Metric serialized to JSON.
 
-The filtered value must be greater than zero; otherwise it will be ignored and a usage warning will result.
+The filtered value must be greater than zero; otherwise it will be ignored, and a usage warning will result.
 
 ### Filter: `od_gzip_url_metric_store_request_payloads` (default: `true` if the `gzdecode()` function exists)
 

plugins/optimization-detective/helper.php

@@ -176,7 +176,7 @@ function od_get_disabled_reasons(): array {
 }
 
 /**
- * Displays the HTML generator meta tag for the Optimization Detective plugin.
+ * Displays the HTML generator META tag for the Optimization Detective plugin.
  *
  * See {@see 'wp_head'}.
  *
@@ -203,7 +203,7 @@ function od_render_generator_meta_tag(): void {
  * @since 0.9.0
  * @access private
  *
- * @param string      $src_path Source path, relative to plugin root.
+ * @param string      $src_path Source path, relative to the plugin root.
  * @param string|null $min_path Minified path. If not supplied, then '.min' is injected before the file extension in the source path.
  * @return string URL to script or stylesheet.
  *

plugins/optimization-detective/optimization.php

@@ -17,7 +17,7 @@
  *
  * This is to implement #43258 in core.
  *
- * This is a hack which would eventually be replaced with something like this in wp-includes/template-loader.php:
+ * This is a hack that would eventually be replaced with something like this in wp-includes/template-loader.php:
  *
  *          $template = apply_filters( 'template_include', $template );
  *     +    ob_start( 'wp_template_output_buffer_callback' );
@@ -40,7 +40,7 @@ function od_buffer_output( $passthrough ) {
 	 * response as an HTML document, this would result in broken HTML processing.
 	 *
 	 * If this ends up being problematic, then PHP_OUTPUT_HANDLER_FLUSHABLE could be added to the $flags and the
-	 * output buffer callback could check if the phase is PHP_OUTPUT_HANDLER_FLUSH and abort any subsequent
+	 * output buffer callback could check if the phase is PHP_OUTPUT_HANDLER_FLUSH and abort any later
 	 * processing while also emitting a _doing_it_wrong().
 	 *
 	 * The output buffer needs to be removable because WordPress calls wp_ob_end_flush_all() and then calls
@@ -52,13 +52,13 @@ function od_buffer_output( $passthrough ) {
 
 	ob_start(
 		static function ( string $output, ?int $phase ): string {
-			// When the output is being cleaned (e.g. pending template is replaced with error page), do not send it through the filter.
+			// When the output is being cleaned (e.g. the pending template is replaced with an error page), do not send it through the filter.
 			if ( ( $phase & PHP_OUTPUT_HANDLER_CLEAN ) !== 0 ) {
 				return $output;
 			}
 
 			/**
-			 * Filters the template output buffer prior to sending to the client.
+			 * Filters the template output buffer before sending it to the client.
 			 *
 			 * @since 0.1.0
 			 * @link https://github.com/WordPress/performance/blob/trunk/plugins/optimization-detective/docs/hooks.md#:~:text=Filter%3A%20od_template_output_buffer

plugins/optimization-detective/tests/test-helper.php

@@ -84,7 +84,7 @@ public function test_od_generate_media_query( ?int $min_width, ?int $max_width,
 	}
 
 	/**
-	 * Test printing the meta generator tag.
+	 * Test printing the META generator tag.
 	 *
 	 * @covers ::od_render_generator_meta_tag
 	 */
@@ -98,7 +98,7 @@ public function test_od_render_generator_meta_tag(): void {
 	}
 
 	/**
-	 * Test meta generator tag when query parameter is present.
+	 * Test META generator tag when query parameter is present.
 	 *
 	 * @covers ::od_render_generator_meta_tag
 	 * @covers ::od_get_disabled_reasons
@@ -111,7 +111,7 @@ public function test_od_render_generator_meta_tag_query_param_disabled(): void {
 	}
 
 	/**
-	 * Test printing the meta generator tag when the REST API is not available.
+	 * Test printing the META generator tag when the REST API is not available.
 	 *
 	 * @covers ::od_render_generator_meta_tag
 	 * @covers ::od_get_disabled_reasons

plugins/optimization-detective/tests/test-optimization.php

@@ -50,7 +50,7 @@ public function test_od_buffer_output(): void {
 		$original = 'Hello World!';
 		$expected = '¡Hola Mundo!';
 
-		// In order to test, a wrapping output buffer is required because ob_get_clean() does not invoke the output
+		// To test, a wrapping output buffer is required because ob_get_clean() does not invoke the output
 		// buffer callback. See <https://stackoverflow.com/a/61439514/93579>.
 		ob_start();
 
@@ -88,7 +88,7 @@ public function test_od_buffer_with_cleaning_and_attempted_flushing(): void {
 		$template_middle  = ', the middle';
 		$template_end     = ', and the end!';
 
-		// In order to test, a wrapping output buffer is required because ob_get_clean() does not invoke the output
+		// To test, a wrapping output buffer is required because ob_get_clean() does not invoke the output
 		// buffer callback. See <https://stackoverflow.com/a/61439514/93579>.
 		$initial_level = ob_get_level();
 		$this->assertTrue( ob_start() );