Fix typos and clarify grammar in documentation and comments

Updated various documentation and in-code comments to fix typos, improve grammar, and enhance clarity. These changes ensure better readability and more precise communication across the codebase, especially in user-facing docs and inline explanations. These issues were flagged via static analysis in PhpStorm.

Author: westonruter

plugins/optimization-detective/class-od-strict-url-metric.php

@@ -16,7 +16,7 @@
  * Representation of the measurements taken from a single client's visit to a specific URL without additionalProperties allowed.
  *
  * This is used exclusively in the REST API endpoint for capturing new URL Metrics to prevent invalid additional data from being
- * submitted in the request. For URL Metrics which have been stored the looser OD_URL_Metric class is used instead.
+ * submitted in the request. For URL Metrics which have been stored, the looser OD_URL_Metric class is used instead.
  *
  * @phpstan-import-type JSONSchema from OD_URL_Metric
  *

plugins/optimization-detective/class-od-tag-visitor-context.php

@@ -124,7 +124,7 @@ public function __get( string $name ) {
 				throw new Error(
 					esc_html(
 						sprintf(
-							/* translators: %s is class member variable name */
+							/* translators: %s is the class member variable name */
 							__( 'Unknown property %s.', 'optimization-detective' ),
 							__CLASS__ . '::$' . $name
 						)

plugins/optimization-detective/class-od-template-optimization-context.php

@@ -114,7 +114,7 @@ public function __get( string $name ) {
 				throw new Error(
 					esc_html(
 						sprintf(
-							/* translators: %s is class member variable name */
+							/* translators: %s is the class member variable name */
 							__( 'Unknown property %s.', 'optimization-detective' ),
 							__CLASS__ . '::$' . $name
 						)

plugins/optimization-detective/class-od-url-metric-group-collection.php

@@ -51,7 +51,7 @@ final class OD_URL_Metric_Group_Collection implements Countable, IteratorAggrega
 	 * value of 1, and the breakpoints are used as the maximum viewport widths for the viewport groups, with the addition of
 	 * a final viewport group which has a maximum viewport width of infinity.
 	 *
-	 * This array may be empty in which case there are no responsive breakpoints and all URL Metrics are collected in a
+	 * This array may be empty, in which case there are no responsive breakpoints, and all URL Metrics are collected in a
 	 * single group.
 	 *
 	 * @since 0.1.0
@@ -153,7 +153,7 @@ public function __construct( array $url_metrics, string $current_etag, array $br
 		 */
 		$this->breakpoints = $breakpoints;
 
-		// Set sample size.
+		// Set the sample size.
 		if ( $sample_size <= 0 ) {
 			throw new InvalidArgumentException(
 				esc_html(
@@ -211,7 +211,7 @@ public function get_sample_size(): int {
 	}
 
 	/**
-	 * Gets the freshness age (TTL) for a given URL Metric..
+	 * Gets the freshness age (TTL) for a given URL Metric.
 	 *
 	 * @since 1.0.0
 	 *
@@ -224,7 +224,7 @@ public function get_freshness_ttl(): int {
 	/**
 	 * Gets the first URL Metric group (with the lowest minimum viewport width, e.g. for mobile).
 	 *
-	 * This group normally represents viewports for mobile devices. This group always has a minimum viewport width of 0
+	 * This group normally represents viewports for mobile devices. This group always has a minimum viewport width of 0,
 	 * and the maximum viewport width corresponds to the smallest defined breakpoint returned by
 	 * {@see od_get_breakpoint_max_widths()}.
 	 *
@@ -241,7 +241,7 @@ public function get_first_group(): OD_URL_Metric_Group {
 	 *
 	 * This group normally represents viewports for desktop devices.  This group always has a minimum viewport width
 	 * defined as one greater than the largest breakpoint returned by {@see od_get_breakpoint_max_widths()}.
-	 * The maximum viewport width of this group is always `null`, or in other words it is unbounded.
+	 * The maximum viewport width of this group is always `null`, or in other words, it is unbounded.
 	 *
 	 * @since 0.7.0
 	 *
@@ -404,7 +404,7 @@ public function is_every_group_populated(): bool {
 	/**
 	 * Checks whether every group is complete (full sample of non-stale URL Metrics).
 	 *
-	 * Completeness means the full sample size of URL Metrics has been collected,
+	 * Completeness means the full sample size of URL Metrics has been collected;
 	 * none of the collected URL Metrics are stale (with a mismatching ETag or a
 	 * timestamp older than the freshness TTL).
 	 *
@@ -520,9 +520,9 @@ public function get_common_lcp_element(): ?OD_Element {
 	/**
 	 * Gets all elements from all URL Metrics from all groups keyed by the elements' XPaths.
 	 *
-	 * This is an O(n^3) function so its results must be cached. This being said, the number of groups should be 4 (one
-	 * more than the default number of breakpoints) and the number of URL Metrics for each group should be 3
-	 * (the default sample size). Therefore, given the number (n) of visited elements on the page this will only
+	 * This is an O(n^3) function, so its results must be cached. This being said, the number of groups should be 4 (one
+	 * more than the default number of breakpoints), and the number of URL Metrics for each group should be 3
+	 * (the default sample size). Therefore, given the number (n) of visited elements on the page, this will only
 	 * end up running n*4*3 times.
 	 *
 	 * @since 0.7.0
@@ -584,8 +584,8 @@ public function get_all_element_max_intersection_ratios(): array {
 	 *
 	 * An element is positioned in the initial viewport if its `boundingClientRect.top` is less than the
 	 * `viewport.height` for any of its recorded URL Metrics. Note that even though the element may be positioned in the
-	 * initial viewport, it may not actually be visible. It could be occluded as a latter slide in a carousel in which
-	 * case it will have intersectionRatio of 0. Or the element may not be visible due to it or an ancestor having the
+	 * initial viewport, it may not actually be visible. It could be occluded as a latter slide in a carousel, in which
+	 * case it will have an intersectionRatio of 0. Or the element may not be visible due to it or an ancestor having the
 	 * `visibility:hidden` style, such as in the case of a dropdown navigation menu. When, for example, an IMG element
 	 * is positioned in any initial viewport, it should not get `loading=lazy` but rather `fetchpriority=low`.
 	 * Furthermore, the element may be positioned _above_ the initial viewport or to the left or right of the viewport,
@@ -624,7 +624,7 @@ public function get_all_elements_positioned_in_any_initial_viewport(): array {
 	 * @since 0.3.0
 	 *
 	 * @param string $xpath XPath for the element.
-	 * @return float|null Max intersection ratio of null if tag is unknown (not captured).
+	 * @return float|null Max intersection ratio or null if the tag is unknown (not captured).
 	 */
 	public function get_element_max_intersection_ratio( string $xpath ): ?float {
 		return $this->get_all_element_max_intersection_ratios()[ $xpath ] ?? null;
@@ -636,7 +636,7 @@ public function get_element_max_intersection_ratio( string $xpath ): ?float {
 	 * @since 0.7.0
 	 *
 	 * @param string $xpath XPath for the element.
-	 * @return bool|null Whether element is positioned in any initial viewport of null if unknown.
+	 * @return bool|null Whether an element is positioned in any initial viewport or null if unknown.
 	 */
 	public function is_element_positioned_in_any_initial_viewport( string $xpath ): ?bool {
 		return $this->get_all_elements_positioned_in_any_initial_viewport()[ $xpath ] ?? null;
@@ -651,8 +651,8 @@ public function is_element_positioned_in_any_initial_viewport( string $xpath ):
 	 */
 	public function get_flattened_url_metrics(): array {
 		// The duplication of iterator_to_array is not a mistake. This collection is an
-		// iterator and the collection contains iterator instances. So to flatten the
-		// two levels of iterators we need to nest calls to iterator_to_array().
+		// iterator, and the collection contains iterator instances. So to flatten the
+		// two levels of iterators, we need to nest calls to iterator_to_array().
 		return array_merge(
 			...array_map(
 				'iterator_to_array',

plugins/optimization-detective/class-od-url-metric-group.php

@@ -268,7 +268,7 @@ static function ( OD_URL_Metric $a, OD_URL_Metric $b ): int {
 	/**
 	 * Determines whether the URL Metric group is complete.
 	 *
-	 * A group is complete if it has the full sample size of URL Metrics
+	 * A group is complete if it has the full sample size of URL Metrics,
 	 * and all of these URL Metrics are fresh (with a current ETag and a
 	 * timestamp that is not older than the freshness TTL).
 	 *
@@ -322,15 +322,15 @@ public function get_lcp_element(): ?OD_Element {
 
 		$result = ( function () {
 
-			// No metrics have been gathered for this group so there is no LCP element.
+			// No metrics have been gathered for this group, so there is no LCP element.
 			if ( count( $this->url_metrics ) === 0 ) {
 				return null;
 			}
 
 			// The following arrays all share array indices.
 
 			/**
-			 * Seen breadcrumbs counts.
+			 * Seen breadcrumb counts.
 			 *
 			 * @var array<int, non-empty-string> $seen_breadcrumbs
 			 */
@@ -350,7 +350,7 @@ public function get_lcp_element(): ?OD_Element {
 			 */
 			$breadcrumb_element = array();
 
-			// Prefer to use URL Metrics which have a current ETag.
+			// Prefer to use URL Metrics, which have a current ETag.
 			$url_metrics = array_filter(
 				$this->url_metrics,
 				function ( OD_URL_Metric $url_metric ): bool {
@@ -459,7 +459,7 @@ public function get_all_element_max_intersection_ratios(): array {
 	 * @since 0.9.0
 	 *
 	 * @param string $xpath XPath for the element.
-	 * @return float|null Max intersection ratio of null if tag is unknown (not captured).
+	 * @return float|null Max intersection ratio or null if the tag is unknown (not captured).
 	 */
 	public function get_element_max_intersection_ratio( string $xpath ): ?float {
 		return $this->get_all_element_max_intersection_ratios()[ $xpath ] ?? null;

plugins/optimization-detective/class-od-url-metric.php

@@ -208,7 +208,7 @@ public static function get_json_schema(): array {
 			)
 		);
 
-		// The spec allows these to be negative but this doesn't make sense in the context of intersectionRect and boundingClientRect.
+		// The spec allows these to be negative, but this doesn't make sense in the context of intersectionRect and boundingClientRect.
 		$dom_rect_properties['width']['minimum']  = 0.0;
 		$dom_rect_properties['height']['minimum'] = 0.0;
 
@@ -312,9 +312,9 @@ public static function get_json_schema(): array {
 				),
 			),
 			// Additional root properties may be added to the schema via the od_url_metric_schema_root_additional_properties filter.
-			// Therefore, additionalProperties is set to true so that additional properties defined in the extended schema may persist
+			// Therefore, `additionalProperties` is set to true so that additional properties defined in the extended schema may persist
 			// in a stored URL Metric even when the extension is deactivated. For REST API requests, the OD_Strict_URL_Metric
-			// which sets this to false so that newly-submitted URL Metrics only ever include the known properties.
+			// which sets this to false so that newly submitted URL Metrics only ever include the known properties.
 			'additionalProperties' => true,
 		);
 
@@ -364,7 +364,7 @@ public static function get_json_schema(): array {
 	protected static function extend_schema_with_optional_properties( array $properties_schema, array $additional_properties, string $filter_name ): array {
 		$doing_it_wrong = static function ( string $message ) use ( $filter_name ): void {
 			_doing_it_wrong(
-				esc_html( "Filter: '{$filter_name}'" ),
+				esc_html( "Filter: '$filter_name'" ),
 				esc_html( $message ),
 				'Optimization Detective 0.6.0'
 			);

plugins/optimization-detective/deprecated.php

@@ -5,6 +5,8 @@
  * @package optimization-detective
  *
  * @since 1.0.0
+ *
+ * @noinspection PhpUnused
  */
 
 // @codeCoverageIgnoreStart

plugins/optimization-detective/detect.js

@@ -27,14 +27,14 @@
  */
 
 /**
- * Window reference to reduce size when script is minified.
+ * Window reference to reduce size when the script is minified.
  *
  * @type {Window}
  */
 const win = window;
 
 /**
- * Document reference to reduce size when script is minified.
+ * Document reference to reduce size when the script is minified.
  *
  * @type {Document}
  */
@@ -184,7 +184,7 @@ function createLogger(
 /**
  * Attempts to get the extension name (i.e. slug for plugin or theme) from the script module URL.
  *
- * If extraction of the slug fails then the entire URL is returned.
+ * If extraction of the slug fails, then the entire URL is returned.
  *
  * @param {string} scriptModuleUrl - Script module URL.
  * @return {string} Derived extension name.
@@ -509,7 +509,7 @@ function debounceCompressUrlMetric() {
  */
 
 /**
- * Detects the LCP element, loaded images, client viewport and store for future optimizations.
+ * Detects the LCP element, loaded images, client viewport, and store for future optimizations.
  *
  * @param {Object}                 args                            - Args.
  * @param {string[]}               args.extensionModuleUrls        - URLs for extension script modules to import.
@@ -669,7 +669,7 @@ export default async function detect( {
 		return;
 	}
 
-	// Keep track of whether the window resized. If it resized, we abort sending the URLMetric.
+	// Keep track of whether the window resized. If it was resized, we abort sending the URLMetric.
 	let didWindowResize = false;
 	window.addEventListener(
 		'resize',
@@ -704,10 +704,10 @@ export default async function detect( {
 	const breadcrumbedElementsMap = new Map(
 		[ ...breadcrumbedElements ].map(
 			/**
-			 * @param {HTMLElement} element
-			 * @return {[HTMLElement, string]} Tuple of element and its XPath.
+			 * @param {Element} element
+			 * @return {[Element, string]} Tuple of an element and its XPath.
 			 */
-			( element ) => [ element, element.dataset.odXpath ]
+			( element ) => [ element, element.getAttribute( 'data-od-xpath' ) ]
 		)
 	);
 
@@ -724,7 +724,7 @@ export default async function detect( {
 		}
 	}
 
-	// Wait for the intersection observer to report back on the initially-visible elements.
+	// Wait for the intersection observer to report back on the initially visible elements.
 	// Note that the first callback will include _all_ observed entries per <https://github.com/w3c/IntersectionObserver/issues/476>.
 	if ( breadcrumbedElementsMap.size > 0 ) {
 		await new Promise( ( resolve ) => {
@@ -756,7 +756,7 @@ export default async function detect( {
 	/** @type {(LCPMetric|LCPMetricWithAttribution)[]} */
 	const lcpMetricCandidates = [];
 
-	// Obtain at least one LCP candidate. More may be reported before the page finishes loading.
+	// Get at least one LCP candidate. More may be reported before the page finishes loading.
 	await new Promise( ( resolve ) => {
 		onLCP(
 			/**
@@ -769,15 +769,15 @@ export default async function detect( {
 				resolve();
 			},
 			{
-				// This avoids needing to click to finalize LCP candidate. While this is helpful for testing, it also
+				// This avoids needing to click to finalize the LCP candidate. While this is helpful for testing, it also
 				// ensures that we always get an LCP candidate reported. Otherwise, the callback may never fire if the
 				// user never does a click or keydown, per <https://github.com/GoogleChrome/web-vitals/blob/07f6f96/src/onLCP.ts#L99-L107>.
 				reportAllChanges: true,
 			}
 		);
 	} );
 
-	// Stop observing initial viewport.
+	// Stop observing the initial viewport.
 	disconnectIntersectionObserver();
 
 	urlMetric = {
@@ -936,7 +936,7 @@ export default async function detect( {
 		);
 	} );
 
-	// Only proceed with submitting the URL Metric if viewport stayed the same size. Changing the viewport size (e.g. due
+	// Only proceed with submitting the URL Metric if the viewport stayed the same size. Changing the viewport size (e.g. due
 	// to resizing a window or changing the orientation of a device) will result in unexpected metrics being collected.
 	if ( didWindowResize ) {
 		log( 'Aborting URL Metric collection due to viewport size change.' );
@@ -1009,7 +1009,7 @@ export default async function detect( {
 	}
 
 	/*
-	 * Now prepare the URL Metric to be sent as JSON request body.
+	 * Now prepare the URL Metric to be sent in the JSON request body.
 	 */
 
 	const maxBodyLengthKiB = 64;

plugins/optimization-detective/detection.php

@@ -13,7 +13,7 @@
 // @codeCoverageIgnoreEnd
 
 /**
- * Obtains the ID for a post related to this response so that page caches can be told to invalidate their cache.
+ * Gets the ID for a post related to this response so that page caches can be told to invalidate their cache.
  *
  * If the queried object for the response is a post, then that post's ID is used. Otherwise, it uses the ID of the first
  * post in The Loop.
@@ -23,15 +23,15 @@
  * this ID if the relevant actions are triggered for the post (e.g. clean_post_cache, save_post, transition_post_status).
  *
  * Otherwise, if the response is an archive page or the front page where show_on_front=posts (i.e. is_home), then
- * there is no singular post object that represents the URL. In this case, we obtain the first post in the main
- * loop. By triggering the relevant actions for this post ID, page caches will have their best shot at invalidating
+ * there is no singular post object that represents the URL. In this case, we get the first post in the main
+ * loop. By triggering the relevant actions for this post ID, page caches will be more likely able to invalidate
  * the related URLs. Page caching plugins which leverage surrogate keys will be the most reliable here. Otherwise,
  * caching plugins may just resort to automatically purging the cache for the homepage whenever any post is edited,
  * which is better than nothing.
  *
  * There should not be any situation by default in which a page optimized with Optimization Detective does not have such
  * a post available for cache purging. As seen in {@see od_can_optimize_response()}, when such a post ID is not
- * available for cache purging then it returns false, as it also does in another case like if is_404().
+ * available for cache purging, then it returns false, as it also does in another case like if is_404().
  *
  * @since 0.8.0
  * @access private