Update phpdoc

Author: westonruter

plugins/optimization-detective/class-od-link-collection.php

@@ -43,13 +43,17 @@ final class OD_Link_Collection implements Countable {
 	/**
 	 * Links grouped by rel type.
 	 *
+	 * @since 0.4.0
+	 *
 	 * @var array<string, Link[]>
 	 */
 	private $links_by_rel = array();
 
 	/**
 	 * Adds link.
 	 *
+	 * @since 0.3.0
+	 *
 	 * @phpstan-param LinkAttributes $attributes
 	 *
 	 * @param array            $attributes             Attributes.
@@ -110,6 +114,8 @@ public function add_link( array $attributes, ?int $minimum_viewport_width = null
 	 * When two links are identical except for their minimum/maximum widths which are also consecutive, then merge them
 	 * together. Also, add media attributes to the links.
 	 *
+	 * @since 0.4.0
+	 *
 	 * @return LinkAttributes[] Prepared links with adjacent-duplicates merged together and media attributes added.
 	 */
 	private function get_prepared_links(): array {
@@ -132,6 +138,8 @@ function ( array $links ): array {
 	/**
 	 * Merges consecutive links.
 	 *
+	 * @since 0.4.0
+	 *
 	 * @param Link[] $links Links.
 	 * @return LinkAttributes[] Merged consecutive links.
 	 */
@@ -227,6 +235,8 @@ static function ( array $link ): array {
 	/**
 	 * Gets the HTML for the link tags.
 	 *
+	 * @since 0.3.0
+	 *
 	 * @return string Link tags HTML.
 	 */
 	public function get_html(): string {
@@ -248,6 +258,8 @@ public function get_html(): string {
 	/**
 	 * Constructs the Link HTTP response header.
 	 *
+	 * @since 0.4.0
+	 *
 	 * @return non-empty-string|null Link HTTP response header, or null if there are none.
 	 */
 	public function get_response_header(): ?string {
@@ -301,6 +313,8 @@ static function ( $matches ) {
 	/**
 	 * Counts the links.
 	 *
+	 * @since 0.3.0
+	 *
 	 * @return non-negative-int Link count.
 	 */
 	public function count(): int {

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

@@ -26,13 +26,17 @@ final class OD_Tag_Visitor_Registry implements Countable, IteratorAggregate {
 	/**
 	 * Visitors.
 	 *
+	 * @since 0.3.0
+	 *
 	 * @var array<non-empty-string, TagVisitorCallback>
 	 */
 	private $visitors = array();
 
 	/**
 	 * Registers a tag visitor.
 	 *
+	 * @since 0.3.0
+	 *
 	 * @phpstan-param TagVisitorCallback $tag_visitor_callback
 	 *
 	 * @param non-empty-string $id                   Identifier for the tag visitor.
@@ -45,6 +49,8 @@ public function register( string $id, callable $tag_visitor_callback ): void {
 	/**
 	 * Determines if a visitor has been registered.
 	 *
+	 * @since 0.3.0
+	 *
 	 * @param non-empty-string $id Identifier for the tag visitor.
 	 * @return bool Whether registered.
 	 */
@@ -55,6 +61,8 @@ public function is_registered( string $id ): bool {
 	/**
 	 * Gets a registered visitor.
 	 *
+	 * @since 0.3.0
+	 *
 	 * @param non-empty-string $id Identifier for the tag visitor.
 	 * @return TagVisitorCallback|null Whether registered.
 	 */
@@ -68,6 +76,8 @@ public function get_registered( string $id ): ?callable {
 	/**
 	 * Unregisters a tag visitor.
 	 *
+	 * @since 0.3.0
+	 *
 	 * @param non-empty-string $id Identifier for the tag visitor.
 	 * @return bool Whether a tag visitor was unregistered.
 	 */
@@ -82,6 +92,8 @@ public function unregister( string $id ): bool {
 	/**
 	 * Returns an iterator for the URL Metrics in the group.
 	 *
+	 * @since 0.3.0
+	 *
 	 * @return ArrayIterator<string, TagVisitorCallback> ArrayIterator for tag visitors.
 	 */
 	public function getIterator(): ArrayIterator {
@@ -91,6 +103,8 @@ public function getIterator(): ArrayIterator {
 	/**
 	 * Counts the URL Metrics in the group.
 	 *
+	 * @since 0.3.0
+	 *
 	 * @return int<0, max> URL Metric count.
 	 */
 	public function count(): int {

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

@@ -30,6 +30,7 @@ final class OD_URL_Metric_Group_Collection implements Countable, IteratorAggrega
 	 * even to when there are zero breakpoints: there will still be one group
 	 * in this case, in which every single URL Metric is added.
 	 *
+	 * @since 0.1.0
 	 * @var OD_URL_Metric_Group[]
 	 * @phpstan-var non-empty-array<OD_URL_Metric_Group>
 	 */
@@ -53,13 +54,15 @@ final class OD_URL_Metric_Group_Collection implements Countable, IteratorAggrega
 	 * 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
 	 * @var positive-int[]
 	 */
 	private $breakpoints;
 
 	/**
 	 * Sample size for URL Metrics for a given breakpoint.
 	 *
+	 * @since 0.1.0
 	 * @var int<1, max>
 	 */
 	private $sample_size;
@@ -69,13 +72,15 @@ final class OD_URL_Metric_Group_Collection implements Countable, IteratorAggrega
 	 *
 	 * A freshness age of zero means a URL Metric will always be considered stale.
 	 *
+	 * @since 0.1.0
 	 * @var int<0, max>
 	 */
 	private $freshness_ttl;
 
 	/**
 	 * Result cache.
 	 *
+	 * @since 0.3.0
 	 * @var array{
 	 *          get_group_for_viewport_width?: array<int, OD_URL_Metric_Group>,
 	 *          is_every_group_populated?: bool,
@@ -93,6 +98,8 @@ final class OD_URL_Metric_Group_Collection implements Countable, IteratorAggrega
 	/**
 	 * Constructor.
 	 *
+	 * @since 0.1.0
+	 *
 	 * @throws InvalidArgumentException When an invalid argument is supplied.
 	 *
 	 * @phpstan-param positive-int[] $breakpoints

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

@@ -94,6 +94,8 @@ final class OD_URL_Metric_Group implements IteratorAggregate, Countable, JsonSer
 	 *
 	 * This class should never be directly constructed. It should only be constructed by the {@see OD_URL_Metric_Group_Collection::create_groups()}.
 	 *
+	 * @since 0.1.0
+	 *
 	 * @access private
 	 * @throws InvalidArgumentException If arguments are invalid.
 	 *

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

@@ -66,13 +66,15 @@ class OD_URL_Metric implements JsonSerializable {
 	/**
 	 * Data.
 	 *
+	 * @since 0.1.0
 	 * @var Data
 	 */
 	protected $data;
 
 	/**
 	 * Elements.
 	 *
+	 * @since 0.7.0
 	 * @var OD_Element[]
 	 */
 	protected $elements;
@@ -88,6 +90,8 @@ class OD_URL_Metric implements JsonSerializable {
 	/**
 	 * Constructor.
 	 *
+	 * @since 0.1.0
+	 *
 	 * @phpstan-param Data|array<string, mixed> $data Valid data or invalid data (in which case an exception is thrown).
 	 *
 	 * @throws OD_Data_Validation_Exception When the input is invalid.
@@ -104,6 +108,8 @@ public function __construct( array $data ) {
 	/**
 	 * Prepares data with validation and sanitization.
 	 *
+	 * @since 0.6.0
+	 *
 	 * @throws OD_Data_Validation_Exception When the input is invalid.
 	 *
 	 * @param array<string, mixed> $data Data to validate.
@@ -349,7 +355,6 @@ public static function get_json_schema(): array {
 	 * @param array<string, mixed> $properties_schema     Properties schema to extend.
 	 * @param array<string, mixed> $additional_properties Additional properties.
 	 * @param string               $filter_name           Filter name used to extend.
-	 *
 	 * @return array<string, mixed> Extended schema.
 	 */
 	protected static function extend_schema_with_optional_properties( array $properties_schema, array $additional_properties, string $filter_name ): array {

plugins/optimization-detective/class-od-visited-tag-state.php

@@ -30,6 +30,8 @@ final class OD_Visited_Tag_State {
 
 	/**
 	 * Constructor.
+	 *
+	 * @since 1.0.0
 	 */
 	public function __construct() {
 		$this->reset();

plugins/optimization-detective/storage/class-od-storage-lock.php

@@ -24,7 +24,6 @@ final class OD_Storage_Lock {
 	 * Capability for being able to store a URL Metric now.
 	 *
 	 * @since n.e.x.t
-	 * @access private
 	 * @var string
 	 */
 	const STORE_URL_METRIC_NOW_CAPABILITY = 'od_store_url_metric_now';
@@ -33,7 +32,6 @@ final class OD_Storage_Lock {
 	 * Adds hooks.
 	 *
 	 * @since n.e.x.t
-	 * @access private
 	 */
 	public static function add_hooks(): void {
 		add_filter( 'user_has_cap', array( __CLASS__, 'filter_user_has_cap' ) );
@@ -43,7 +41,6 @@ public static function add_hooks(): void {
 	 * Filters `user_has_cap` to grant the `od_store_url_metric_now` capability to users who can `manage_options` by default.
 	 *
 	 * @since n.e.x.t
-	 * @access private
 	 *
 	 * @param array<string, bool>|mixed $allcaps Capability names mapped to boolean values for whether the user has that capability.
 	 * @return array<string, bool> Capability names mapped to boolean values for whether the user has that capability.
@@ -94,6 +91,8 @@ public static function get_ttl(): int {
 	/**
 	 * Gets transient key for locking URL Metric storage (for the current IP).
 	 *
+	 * @since 0.1.0
+	 *
 	 * @todo Should the URL be included in the key? Or should a user only be allowed to store one metric?
 	 * @return non-empty-string Transient key.
 	 */

plugins/optimization-detective/storage/class-od-url-metrics-post-type.php

@@ -23,20 +23,23 @@ class OD_URL_Metrics_Post_Type {
 	/**
 	 * Post type slug.
 	 *
+	 * @since 0.1.0
 	 * @var string
 	 */
 	const SLUG = 'od_url_metrics';
 
 	/**
 	 * Event name (hook) for garbage collection of stale URL Metrics posts.
 	 *
+	 * @since 0.1.0
 	 * @var string
 	 */
 	const GC_CRON_EVENT_NAME = 'od_url_metrics_gc';
 
 	/**
 	 * Recurrence for garbage collection of stale URL Metrics posts.
 	 *
+	 * @since 0.1.0
 	 * @var string
 	 */
 	const GC_CRON_RECURRENCE = 'daily';

plugins/optimization-detective/storage/rest-api.php

@@ -15,6 +15,8 @@
 /**
  * Namespace for optimization-detective.
  *
+ * @since 0.1.0
+ * @access private
  * @var string
  */
 const OD_REST_API_NAMESPACE = 'optimization-detective/v1';
@@ -26,6 +28,8 @@
  * that does not strictly follow the standard usage. Namely, submitting a POST request to this endpoint will either
  * create a new `od_url_metrics` post, or it will update an existing post if one already exists for the provided slug.
  *
+ * @since 0.1.0
+ * @access private
  * @link https://google.aip.dev/136
  * @var string
  */