From 22ac96058acd77e30e2bc80fff65c21e9b4e006b Mon Sep 17 00:00:00 2001
From: Lee Rowlands <lee.rowlands@previousnext.com.au>
Date: Fri, 3 Jan 2025 10:56:08 +1000
Subject: [PATCH] Issue #3484040 by quietone: Fix
Drupal.Commenting.FunctionComment.MissingReturnComment in components
---
.../Component/Annotation/AnnotationInterface.php | 3 +++
.../Plugin/Discovery/AnnotatedClassDiscovery.php | 1 +
core/lib/Drupal/Component/Datetime/DateTimePlus.php | 1 +
core/lib/Drupal/Component/Discovery/YamlDiscovery.php | 2 ++
core/lib/Drupal/Component/Gettext/PoItem.php | 10 +++++++---
core/lib/Drupal/Component/Gettext/PoMemoryWriter.php | 3 ++-
.../HttpFoundation/SecuredRedirectResponse.php | 1 +
.../Component/Plugin/Attribute/AttributeInterface.php | 3 +++
.../Plugin/Discovery/AttributeClassDiscovery.php | 1 +
core/lib/Drupal/Component/Plugin/PluginManagerBase.php | 2 ++
.../lib/Drupal/Component/ProxyBuilder/ProxyBuilder.php | 6 ++++++
.../lib/Drupal/Component/Utility/DeprecationHelper.php | 4 ++++
core/lib/Drupal/Component/Utility/Random.php | 7 ++++++-
core/phpcs.xml.dist | 1 +
14 files changed, 40 insertions(+), 5 deletions(-)
diff --git a/core/lib/Drupal/Component/Annotation/AnnotationInterface.php b/core/lib/Drupal/Component/Annotation/AnnotationInterface.php
index eb44b398193e..bb0fdbcb9460 100644
--- a/core/lib/Drupal/Component/Annotation/AnnotationInterface.php
+++ b/core/lib/Drupal/Component/Annotation/AnnotationInterface.php
@@ -16,6 +16,7 @@ public function get();
* Gets the name of the provider of the annotated class.
*
* @return string
+ * The provider of the annotated class.
*/
public function getProvider();
@@ -31,6 +32,7 @@ public function setProvider($provider);
* Gets the unique ID for this annotated class.
*
* @return string
+ * The annotated class ID.
*/
public function getId();
@@ -38,6 +40,7 @@ public function getId();
* Gets the class of the annotated class.
*
* @return string
+ * The class name of the annotated class.
*/
public function getClass();
diff --git a/core/lib/Drupal/Component/Annotation/Plugin/Discovery/AnnotatedClassDiscovery.php b/core/lib/Drupal/Component/Annotation/Plugin/Discovery/AnnotatedClassDiscovery.php
index 27ad81572dfe..d23a91286de7 100644
--- a/core/lib/Drupal/Component/Annotation/Plugin/Discovery/AnnotatedClassDiscovery.php
+++ b/core/lib/Drupal/Component/Annotation/Plugin/Discovery/AnnotatedClassDiscovery.php
@@ -181,6 +181,7 @@ protected function prepareAnnotationDefinition(AnnotationInterface $annotation,
* Gets an array of PSR-4 namespaces to search for plugin classes.
*
* @return string[]
+ * The PSR-4 namespaces for the plugin class.
*/
protected function getPluginNamespaces() {
return $this->pluginNamespaces;
diff --git a/core/lib/Drupal/Component/Datetime/DateTimePlus.php b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
index 35f2e80f0d33..bb3a9b978911 100644
--- a/core/lib/Drupal/Component/Datetime/DateTimePlus.php
+++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
@@ -327,6 +327,7 @@ public function __construct($time = 'now', $timezone = NULL, $settings = []) {
* Renders the timezone name.
*
* @return string
+ * The formatted value of the date including the name of the timezone.
*/
public function render() {
return $this->format(static::FORMAT) . ' ' . $this->getTimeZone()->getName();
diff --git a/core/lib/Drupal/Component/Discovery/YamlDiscovery.php b/core/lib/Drupal/Component/Discovery/YamlDiscovery.php
index 6bbc62ee73a6..74310492bd96 100644
--- a/core/lib/Drupal/Component/Discovery/YamlDiscovery.php
+++ b/core/lib/Drupal/Component/Discovery/YamlDiscovery.php
@@ -77,6 +77,7 @@ public function findAll() {
* Yaml file path.
*
* @return array
+ * The decoded contents of the YAML file.
*/
protected function decode($file) {
try {
@@ -91,6 +92,7 @@ protected function decode($file) {
* Returns an array of file paths, keyed by provider.
*
* @return array
+ * An array of file paths.
*/
protected function findFiles() {
$files = [];
diff --git a/core/lib/Drupal/Component/Gettext/PoItem.php b/core/lib/Drupal/Component/Gettext/PoItem.php
index 41014c9648d6..7cc32568ad23 100644
--- a/core/lib/Drupal/Component/Gettext/PoItem.php
+++ b/core/lib/Drupal/Component/Gettext/PoItem.php
@@ -67,7 +67,8 @@ class PoItem {
/**
* Gets the language code of the currently used language.
*
- * @return string with langcode
+ * @return string
+ * The language code for this item.
*/
public function getLangcode() {
return $this->langcode;
@@ -86,7 +87,8 @@ public function setLangcode($langcode) {
/**
* Gets the context this translation belongs to.
*
- * @return string $context
+ * @return string
+ * The context for this translation.
*/
public function getContext() {
return $this->context;
@@ -157,6 +159,7 @@ public function setPlural($plural) {
* Get if the translation has plural values.
*
* @return bool
+ * TRUE if the translation has plurals, otherwise FALSE.
*/
public function isPlural() {
return $this->plural;
@@ -165,7 +168,8 @@ public function isPlural() {
/**
* Gets the comment of this translation.
*
- * @return String $comment
+ * @return string
+ * The comment of this translation.
*/
public function getComment() {
return $this->comment;
diff --git a/core/lib/Drupal/Component/Gettext/PoMemoryWriter.php b/core/lib/Drupal/Component/Gettext/PoMemoryWriter.php
index 5f32e462c931..b4d28b5d7697 100644
--- a/core/lib/Drupal/Component/Gettext/PoMemoryWriter.php
+++ b/core/lib/Drupal/Component/Gettext/PoMemoryWriter.php
@@ -46,7 +46,8 @@ public function writeItems(PoReaderInterface $reader, $count = -1) {
/**
* Get all stored PoItem's.
*
- * @return array PoItem
+ * @return array
+ * Array of all PoItem elements.
*/
public function getData() {
return $this->items;
diff --git a/core/lib/Drupal/Component/HttpFoundation/SecuredRedirectResponse.php b/core/lib/Drupal/Component/HttpFoundation/SecuredRedirectResponse.php
index 37c01a1b5647..df039b8580a8 100644
--- a/core/lib/Drupal/Component/HttpFoundation/SecuredRedirectResponse.php
+++ b/core/lib/Drupal/Component/HttpFoundation/SecuredRedirectResponse.php
@@ -67,6 +67,7 @@ public function setTargetUrl($url): static {
* The URL checked for safety.
*
* @return bool
+ * Returns TRUE if the URL is safe, FALSE otherwise.
*/
abstract protected function isSafe($url);
diff --git a/core/lib/Drupal/Component/Plugin/Attribute/AttributeInterface.php b/core/lib/Drupal/Component/Plugin/Attribute/AttributeInterface.php
index 30964398a90f..4c1e96810a73 100644
--- a/core/lib/Drupal/Component/Plugin/Attribute/AttributeInterface.php
+++ b/core/lib/Drupal/Component/Plugin/Attribute/AttributeInterface.php
@@ -16,6 +16,7 @@ public function get(): mixed;
* Gets the name of the provider of the attribute class.
*
* @return string|null
+ * The provider of the attribute class.
*/
public function getProvider(): ?string;
@@ -31,6 +32,7 @@ public function setProvider(string $provider): void;
* Gets the unique ID for this attribute class.
*
* @return string
+ * The attribute class ID.
*/
public function getId(): string;
@@ -38,6 +40,7 @@ public function getId(): string;
* Gets the class of the attribute class.
*
* @return class-string|null
+ * The attribute class.
*/
public function getClass(): ?string;
diff --git a/core/lib/Drupal/Component/Plugin/Discovery/AttributeClassDiscovery.php b/core/lib/Drupal/Component/Plugin/Discovery/AttributeClassDiscovery.php
index 14c25f2f3f3c..59a220d4f1a9 100644
--- a/core/lib/Drupal/Component/Plugin/Discovery/AttributeClassDiscovery.php
+++ b/core/lib/Drupal/Component/Plugin/Discovery/AttributeClassDiscovery.php
@@ -166,6 +166,7 @@ protected function prepareAttributeDefinition(AttributeInterface $attribute, str
* Gets an array of PSR-4 namespaces to search for plugin classes.
*
* @return string[][]
+ * An array of namespaces to search.
*/
protected function getPluginNamespaces(): array {
return $this->pluginNamespaces;
diff --git a/core/lib/Drupal/Component/Plugin/PluginManagerBase.php b/core/lib/Drupal/Component/Plugin/PluginManagerBase.php
index d95bbf032702..55343a27dad4 100644
--- a/core/lib/Drupal/Component/Plugin/PluginManagerBase.php
+++ b/core/lib/Drupal/Component/Plugin/PluginManagerBase.php
@@ -37,6 +37,7 @@ abstract class PluginManagerBase implements PluginManagerInterface {
* Gets the plugin discovery.
*
* @return \Drupal\Component\Plugin\Discovery\DiscoveryInterface
+ * The plugin discovery.
*/
protected function getDiscovery() {
return $this->discovery;
@@ -46,6 +47,7 @@ protected function getDiscovery() {
* Gets the plugin factory.
*
* @return \Drupal\Component\Plugin\Factory\FactoryInterface
+ * The plugin factory.
*/
protected function getFactory() {
return $this->factory;
diff --git a/core/lib/Drupal/Component/ProxyBuilder/ProxyBuilder.php b/core/lib/Drupal/Component/ProxyBuilder/ProxyBuilder.php
index 63d72bccb473..1e9fca562f5d 100644
--- a/core/lib/Drupal/Component/ProxyBuilder/ProxyBuilder.php
+++ b/core/lib/Drupal/Component/ProxyBuilder/ProxyBuilder.php
@@ -167,6 +167,7 @@ public function build($class_name) {
* Generates the string for the method which loads the actual service.
*
* @return string
+ * A string for the lazyLoadItself method.
*/
protected function buildLazyLoadItselfMethod() {
$output = <<<'EOS'
@@ -197,6 +198,7 @@ protected function lazyLoadItself()
* A reflection method for the method.
*
* @return string
+ * The docblock, signature, and body for a method.
*/
protected function buildMethod(\ReflectionMethod $reflection_method) {
@@ -260,6 +262,7 @@ protected function buildMethod(\ReflectionMethod $reflection_method) {
* A reflection object of the parameter.
*
* @return string
+ * A parameter string.
*/
protected function buildParameter(\ReflectionParameter $parameter) {
$parameter_string = '';
@@ -301,6 +304,7 @@ protected function buildParameter(\ReflectionParameter $parameter) {
* A reflection method for the method.
*
* @return string
+ * The body for a method.
*/
protected function buildMethodBody(\ReflectionMethod $reflection_method) {
$output = '';
@@ -335,6 +339,7 @@ protected function buildMethodBody(\ReflectionMethod $reflection_method) {
* Builds the constructor used to inject the actual service ID.
*
* @return string
+ * The constructor for a class.
*/
protected function buildConstructorMethod() {
$output = <<<'EOS'
@@ -361,6 +366,7 @@ public function __construct(\Symfony\Component\DependencyInjection\ContainerInte
* Build the required use statements of the proxy class.
*
* @return string
+ * The use statements.
*/
protected function buildUseStatements() {
$output = '';
diff --git a/core/lib/Drupal/Component/Utility/DeprecationHelper.php b/core/lib/Drupal/Component/Utility/DeprecationHelper.php
index e801a48ed659..e62ef3f71061 100644
--- a/core/lib/Drupal/Component/Utility/DeprecationHelper.php
+++ b/core/lib/Drupal/Component/Utility/DeprecationHelper.php
@@ -31,6 +31,10 @@ final class DeprecationHelper {
* Callback for deprecated code path.
*
* @return Current|Deprecated
+ * The method to invoke based on the current version and the version of the
+ * deprecation. The current callback when the current version is greater
+ * than or equal to the version of the deprecation. Otherwise, the
+ * deprecated callback.
*/
public static function backwardsCompatibleCall(string $currentVersion, string $deprecatedVersion, callable $currentCallable, callable $deprecatedCallable): mixed {
// Normalize the version string when it's a dev version to the first point release of that minor. E.g. 10.2.x-dev
diff --git a/core/lib/Drupal/Component/Utility/Random.php b/core/lib/Drupal/Component/Utility/Random.php
index a23fd11a164e..b72e5f90804f 100644
--- a/core/lib/Drupal/Component/Utility/Random.php
+++ b/core/lib/Drupal/Component/Utility/Random.php
@@ -183,12 +183,16 @@ public function machineName(int $length = 8, bool $unique = FALSE): string {
}
/**
- * Generate a string that looks like a word (letters only, alternating consonants and vowels).
+ * Generates a string that looks like a word.
+ *
+ * The generated string contains only letters and has alternating consonants
+ * and vowels.
*
* @param int $length
* The desired word length.
*
* @return string
+ * A random string with the requested number of random words.
*/
public function word($length) {
$vowels = ["a", "e", "i", "o", "u"];
@@ -304,6 +308,7 @@ public function sentences($min_word_count, $capitalize = FALSE) {
* The number of paragraphs to create. Defaults to 12.
*
* @return string
+ * A string of multiple paragraphs.
*/
public function paragraphs($paragraph_count = 12) {
$output = '';
diff --git a/core/phpcs.xml.dist b/core/phpcs.xml.dist
index 887121e72fa0..71441e9c7c4b 100644
--- a/core/phpcs.xml.dist
+++ b/core/phpcs.xml.dist
@@ -87,6 +87,7 @@
</rule>
<rule ref="Drupal.Commenting.FunctionComment.MissingReturnComment">
<include-pattern>core/lib/Drupal/Core/*</include-pattern>
+ <include-pattern>core/lib/Drupal/Component/*</include-pattern>
</rule>
<rule ref="Drupal.Commenting.GenderNeutralComment"/>
<rule ref="Drupal.Commenting.HookComment"/>
--
GitLab