docs(comments): Add short comments to doc blocks, part 1 (#1137)

Author: klausi

phpcs.xml.dist

@@ -18,67 +18,6 @@
   </rule>
 
   <rule ref="Drupal.Commenting.DocComment.MissingShort">
-    <exclude-pattern>src/GraphQL/Resolver/Path.php</exclude-pattern>
-    <exclude-pattern>src/GraphQL/ResolverRegistryInterface.php</exclude-pattern>
-    <exclude-pattern>src/GraphQL/Execution/Executor.php</exclude-pattern>
-    <exclude-pattern>src/GraphQL/Execution/FieldContext.php</exclude-pattern>
-    <exclude-pattern>src/GraphQL/Execution/ExecutorFactory.php</exclude-pattern>
-    <exclude-pattern>src/GraphQL/Execution/ResolveContext.php</exclude-pattern>
-    <exclude-pattern>src/GraphQL/ResolverBuilder.php</exclude-pattern>
-    <exclude-pattern>src/GraphQL/Utility/DocumentSerializer.php</exclude-pattern>
-    <exclude-pattern>src/GraphQL/Utility/DeferredUtility.php</exclude-pattern>
-    <exclude-pattern>src/GraphQL/ResolverRegistry.php</exclude-pattern>
-    <exclude-pattern>src/GraphQL/Buffers/BufferBase.php</exclude-pattern>
-    <exclude-pattern>src/Event/OperationEvent.php</exclude-pattern>
-    <exclude-pattern>src/Form/PersistedQueriesForm.php</exclude-pattern>
-    <exclude-pattern>src/Form/ServerForm.php</exclude-pattern>
-    <exclude-pattern>src/EventSubscriber/CurrentLanguageResetTrait.php</exclude-pattern>
-    <exclude-pattern>src/Entity/ServerInterface.php</exclude-pattern>
-    <exclude-pattern>src/Entity/Server.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/LanguageNegotiation/OperationLanguageNegotiation.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/DataProducerPluginInterface.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/String/Uppercase.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/XML/XMLParse.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/XML/XMLContent.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/XML/XMLAttribute.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/XML/XMLXpath.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/TypedData/PropertyPath.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/DataProducerProxy.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Images/ImageResourceUrl.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Field/EntityReference.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLinks.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuTree/MenuTreeLink.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuTree/MenuTreeSubtree.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLink/MenuLinkAttribute.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLink/MenuLinkUrl.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLink/MenuLinkExpanded.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLink/MenuLinkLabel.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLink/MenuLinkDescription.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Utility/Seek.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Routing/Url/UrlPath.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Routing/RouteLoad.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Routing/RouteEntity.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityPublished.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityLabel.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityRendered.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityType.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityLanguage.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityUrl.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityLoadMultiple.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityOwner.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityCreated.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityDescription.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityTranslation.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityLoad.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityTranslations.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/Fields/Image/ImageDerivative.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/Fields/Image/ImageUrl.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityChanged.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityId.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityUuid.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityAccess.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityLoadByUuid.php</exclude-pattern>
-    <exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityBundle.php</exclude-pattern>
     <exclude-pattern>src/Plugin/GraphQL/Schema/SdlSchemaPluginBase.php</exclude-pattern>
     <exclude-pattern>src/Plugin/GraphQL/Schema/ComposableSchema.php</exclude-pattern>
     <exclude-pattern>src/Plugin/DataProducerPluginManager.php</exclude-pattern>

src/Controller/RequestController.php

@@ -64,10 +64,13 @@ public function handleRequest(ServerInterface $graphql_server, $operations) {
   }
 
   /**
+   * Execute a single operation and turn that into a cacheable response.
+   *
    * @param \Drupal\graphql\Entity\ServerInterface $server
    * @param \GraphQL\Server\OperationParams $operation
    *
    * @return \Drupal\Core\Cache\CacheableJsonResponse
+   *
    * @throws \Exception
    */
   protected function handleSingle(ServerInterface $server, OperationParams $operation) {
@@ -78,10 +81,13 @@ protected function handleSingle(ServerInterface $server, OperationParams $operat
   }
 
   /**
+   * Execute multiple operations as batch and turn that into cacheable response.
+   *
    * @param \Drupal\graphql\Entity\ServerInterface $server
    * @param \GraphQL\Server\OperationParams[] $operations
    *
    * @return \Drupal\Core\Cache\CacheableJsonResponse
+   *
    * @throws \Exception
    */
   protected function handleBatch(ServerInterface $server, array $operations) {

src/Entity/Server.php

@@ -231,10 +231,10 @@ public function configuration() {
   }
 
   /**
-   * @todo Handle this through configuration (e.g. a context value).
-   *
    * Returns to root value to use when resolving queries against the schema.
    *
+   * @todo Handle this through configuration (e.g. a context value).
+   *
    * May return a callable to resolve the root value at run-time based on the
    * provided query parameters / operation.
    *
@@ -307,10 +307,10 @@ protected function getContext(SchemaPluginInterface $schema, array $config) {
   }
 
   /**
-   * @todo Handle this through configuration on the server.
-   *
    * Returns the default field resolver.
    *
+   * @todo Handle this through configuration on the server.
+   *
    * Fields that don't explicitly declare a field resolver will use this one
    * as a fallback.
    *
@@ -353,10 +353,10 @@ protected function getErrorFormatter() {
   }
 
   /**
-   * @todo Handle this through configurable plugins on the server.
-   *
    * Returns the error handler.
    *
+   * @todo Handle this through configurable plugins on the server.
+   *
    * Allows to replace the default error handler with a custom one. For example
    * when there is a need to handle specific errors differently.
    *
@@ -443,8 +443,6 @@ public function getSortedPersistedQueryInstances() {
   }
 
   /**
-   * @todo Handle this through configurable plugins on the server.
-   *
    * Returns a callable for loading persisted queries.
    *
    * @return callable
@@ -465,10 +463,10 @@ protected function getPersistedQueryLoader() {
   }
 
   /**
-   * @todo Handle this through configurable plugins on the server.
-   *
    * Returns the validation rules to use for the query.
    *
+   * @todo Handle this through configurable plugins on the server.
+   *
    * May return a callable to allow the server to decide the validation rules
    * independently for each query operation.
    *

src/Entity/ServerInterface.php

@@ -12,13 +12,17 @@
 interface ServerInterface extends ConfigEntityInterface {
 
   /**
+   * Execute an operation on this server.
+   *
    * @param \GraphQL\Server\OperationParams $operation
    *
    * @return \Drupal\graphql\GraphQL\Execution\ExecutionResult
    */
   public function executeOperation(OperationParams $operation);
 
   /**
+   * Execute multiple operations as batch on this server.
+   *
    * @param \GraphQL\Server\OperationParams[] $operations
    *
    * @return \Drupal\graphql\GraphQL\Execution\ExecutionResult[]

src/Event/OperationEvent.php

@@ -26,11 +26,15 @@ class OperationEvent extends Event {
   const GRAPHQL_OPERATION_AFTER = 'graphql.operation.after';
 
   /**
+   * Result of the query execution.
+   *
    * @var \GraphQL\Executor\ExecutionResult
    */
   protected $result;
 
   /**
+   * Resolver context used for the query.
+   *
    * @var \Drupal\graphql\GraphQL\Execution\ResolveContext
    */
   protected $context;
@@ -47,13 +51,17 @@ public function __construct(ResolveContext $context, ExecutionResult $result = N
   }
 
   /**
+   * Returns the execution result.
+   *
    * @return \GraphQL\Executor\ExecutionResult
    */
   public function getResult() {
     return $this->result;
   }
 
   /**
+   * Returns the resolver context.
+   *
    * @return \Drupal\graphql\GraphQL\Execution\ResolveContext
    */
   public function getContext() {

src/EventSubscriber/CurrentLanguageResetTrait.php

@@ -10,21 +10,29 @@
 trait CurrentLanguageResetTrait {
 
   /**
+   * The language manager.
+   *
    * @var \Drupal\Core\Language\LanguageManagerInterface
    */
   protected $languageManager;
 
   /**
+   * The language negotiator.
+   *
    * @var \Drupal\language\LanguageNegotiatorInterface
    */
   protected $languageNegotiator;
 
   /**
+   * The translator.
+   *
    * @var \Drupal\Core\StringTranslation\Translator\TranslatorInterface
    */
   protected $translator;
 
   /**
+   * The current user service.
+   *
    * @var \Drupal\Core\Session\AccountInterface
    */
   protected $currentUser;

src/Form/PersistedQueriesForm.php

@@ -16,6 +16,8 @@
 class PersistedQueriesForm extends EntityForm {
 
   /**
+   * Plugin manager for persisted query plugins.
+   *
    * @var \Drupal\graphql\Plugin\PersistedQueryPluginManager
    */
   protected $persistedQueryPluginManager;

src/GraphQL/Buffers/BufferBase.php

@@ -22,8 +22,11 @@ abstract class BufferBase {
   protected $results = [];
 
   /**
+   * Returns the bucket name for grouping items together.
+   *
    * @param object $item
    *   The item to get the buffer id for.
+   *
    * @return string
    *   The buffer id.
    */

src/GraphQL/Execution/Executor.php

@@ -62,41 +62,57 @@ class Executor implements ExecutorImplementation {
   protected $dispatcher;
 
   /**
+   * The adapter for promises.
+   *
    * @var \GraphQL\Executor\Promise\PromiseAdapter
    */
   protected $adapter;
 
   /**
+   * Represents the GraphQL schema document.
+   *
    * @var \GraphQL\Language\AST\DocumentNode
    */
   protected $document;
 
   /**
+   * The context to pass down during field resolving.
+   *
    * @var \Drupal\graphql\GraphQL\Execution\ResolveContext
    */
   protected $context;
 
   /**
+   * The root of the GraphQL execution tree.
+   *
    * @var mixed
    */
   protected $root;
 
   /**
+   * Variables.
+   *
    * @var array
    */
   protected $variables;
 
   /**
+   * The parsed GraphQL schema.
+   *
    * @var \GraphQL\Type\Schema
    */
   protected $schema;
 
   /**
+   * The operation to be performed.
+   *
    * @var string
    */
   protected $operation;
 
   /**
+   * The resolver to get results for the query.
+   *
    * @var callable
    */
   protected $resolver;
@@ -151,6 +167,8 @@ public function __construct(
   }
 
   /**
+   * Constructs an object from a services container.
+   *
    * @param \Symfony\Component\DependencyInjection\ContainerInterface $container
    * @param \GraphQL\Executor\Promise\PromiseAdapter $adapter
    * @param \GraphQL\Type\Schema $schema
@@ -212,6 +230,8 @@ public function doExecute(): Promise {
   }
 
   /**
+   * Try to return cached results, otherwise resolve the query.
+   *
    * @param string $prefix
    *
    * @return \GraphQL\Executor\Promise\Promise
@@ -237,6 +257,8 @@ protected function doExecuteCached($prefix) {
   }
 
   /**
+   * Get query results on a cache miss.
+   *
    * @return \GraphQL\Executor\Promise\Promise
    */
   protected function doExecuteUncached() {
@@ -263,6 +285,8 @@ protected function doExecuteUncached() {
   }
 
   /**
+   * Calculates the cache prefix from context for the current query.
+   *
    * @return string
    */
   protected function cachePrefix() {
@@ -285,6 +309,8 @@ protected function cachePrefix() {
   }
 
   /**
+   * Calculate the cache suffix for the current contexts.
+   *
    * @param array $contexts
    *
    * @return string
@@ -295,6 +321,8 @@ protected function cacheSuffix(array $contexts = []) {
   }
 
   /**
+   * Lookup cached results by contexts for this query.
+   *
    * @param string $prefix
    *
    * @return \GraphQL\Executor\ExecutionResult|null
@@ -313,6 +341,8 @@ protected function cacheRead($prefix) {
   }
 
   /**
+   * Store results in cache.
+   *
    * @param string $prefix
    * @param \Drupal\graphql\GraphQL\Execution\ExecutionResult $result
    *

src/GraphQL/Execution/ExecutorFactory.php

@@ -13,6 +13,8 @@
 class ExecutorFactory {
 
   /**
+   * The service container.
+   *
    * @var \Symfony\Component\DependencyInjection\ContainerInterface
    */
   protected $container;
@@ -27,6 +29,8 @@ public function __construct(ContainerInterface $container) {
   }
 
   /**
+   * Factory method to make a new executor.
+   *
    * @param \GraphQL\Executor\Promise\PromiseAdapter $adapter
    * @param \GraphQL\Type\Schema $schema
    * @param \GraphQL\Language\AST\DocumentNode $document