Skip to content

Commit 914534d

Browse files
authored
docs(comments): Add short comments to doc blocks, part 1 (#1137)
1 parent c41752f commit 914534d

65 files changed

Lines changed: 392 additions & 93 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

phpcs.xml.dist

Lines changed: 0 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -18,67 +18,6 @@
1818
</rule>
1919

2020
<rule ref="Drupal.Commenting.DocComment.MissingShort">
21-
<exclude-pattern>src/GraphQL/Resolver/Path.php</exclude-pattern>
22-
<exclude-pattern>src/GraphQL/ResolverRegistryInterface.php</exclude-pattern>
23-
<exclude-pattern>src/GraphQL/Execution/Executor.php</exclude-pattern>
24-
<exclude-pattern>src/GraphQL/Execution/FieldContext.php</exclude-pattern>
25-
<exclude-pattern>src/GraphQL/Execution/ExecutorFactory.php</exclude-pattern>
26-
<exclude-pattern>src/GraphQL/Execution/ResolveContext.php</exclude-pattern>
27-
<exclude-pattern>src/GraphQL/ResolverBuilder.php</exclude-pattern>
28-
<exclude-pattern>src/GraphQL/Utility/DocumentSerializer.php</exclude-pattern>
29-
<exclude-pattern>src/GraphQL/Utility/DeferredUtility.php</exclude-pattern>
30-
<exclude-pattern>src/GraphQL/ResolverRegistry.php</exclude-pattern>
31-
<exclude-pattern>src/GraphQL/Buffers/BufferBase.php</exclude-pattern>
32-
<exclude-pattern>src/Event/OperationEvent.php</exclude-pattern>
33-
<exclude-pattern>src/Form/PersistedQueriesForm.php</exclude-pattern>
34-
<exclude-pattern>src/Form/ServerForm.php</exclude-pattern>
35-
<exclude-pattern>src/EventSubscriber/CurrentLanguageResetTrait.php</exclude-pattern>
36-
<exclude-pattern>src/Entity/ServerInterface.php</exclude-pattern>
37-
<exclude-pattern>src/Entity/Server.php</exclude-pattern>
38-
<exclude-pattern>src/Plugin/LanguageNegotiation/OperationLanguageNegotiation.php</exclude-pattern>
39-
<exclude-pattern>src/Plugin/DataProducerPluginInterface.php</exclude-pattern>
40-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/String/Uppercase.php</exclude-pattern>
41-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/XML/XMLParse.php</exclude-pattern>
42-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/XML/XMLContent.php</exclude-pattern>
43-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/XML/XMLAttribute.php</exclude-pattern>
44-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/XML/XMLXpath.php</exclude-pattern>
45-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/TypedData/PropertyPath.php</exclude-pattern>
46-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/DataProducerProxy.php</exclude-pattern>
47-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Images/ImageResourceUrl.php</exclude-pattern>
48-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Field/EntityReference.php</exclude-pattern>
49-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLinks.php</exclude-pattern>
50-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuTree/MenuTreeLink.php</exclude-pattern>
51-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuTree/MenuTreeSubtree.php</exclude-pattern>
52-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLink/MenuLinkAttribute.php</exclude-pattern>
53-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLink/MenuLinkUrl.php</exclude-pattern>
54-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLink/MenuLinkExpanded.php</exclude-pattern>
55-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLink/MenuLinkLabel.php</exclude-pattern>
56-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Menu/MenuLink/MenuLinkDescription.php</exclude-pattern>
57-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Utility/Seek.php</exclude-pattern>
58-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Routing/Url/UrlPath.php</exclude-pattern>
59-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Routing/RouteLoad.php</exclude-pattern>
60-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Routing/RouteEntity.php</exclude-pattern>
61-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityPublished.php</exclude-pattern>
62-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityLabel.php</exclude-pattern>
63-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityRendered.php</exclude-pattern>
64-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityType.php</exclude-pattern>
65-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityLanguage.php</exclude-pattern>
66-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityUrl.php</exclude-pattern>
67-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityLoadMultiple.php</exclude-pattern>
68-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityOwner.php</exclude-pattern>
69-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityCreated.php</exclude-pattern>
70-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityDescription.php</exclude-pattern>
71-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityTranslation.php</exclude-pattern>
72-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityLoad.php</exclude-pattern>
73-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityTranslations.php</exclude-pattern>
74-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/Fields/Image/ImageDerivative.php</exclude-pattern>
75-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/Fields/Image/ImageUrl.php</exclude-pattern>
76-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityChanged.php</exclude-pattern>
77-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityId.php</exclude-pattern>
78-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityUuid.php</exclude-pattern>
79-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityAccess.php</exclude-pattern>
80-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityLoadByUuid.php</exclude-pattern>
81-
<exclude-pattern>src/Plugin/GraphQL/DataProducer/Entity/EntityBundle.php</exclude-pattern>
8221
<exclude-pattern>src/Plugin/GraphQL/Schema/SdlSchemaPluginBase.php</exclude-pattern>
8322
<exclude-pattern>src/Plugin/GraphQL/Schema/ComposableSchema.php</exclude-pattern>
8423
<exclude-pattern>src/Plugin/DataProducerPluginManager.php</exclude-pattern>

src/Controller/RequestController.php

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,10 +64,13 @@ public function handleRequest(ServerInterface $graphql_server, $operations) {
6464
}
6565

6666
/**
67+
* Execute a single operation and turn that into a cacheable response.
68+
*
6769
* @param \Drupal\graphql\Entity\ServerInterface $server
6870
* @param \GraphQL\Server\OperationParams $operation
6971
*
7072
* @return \Drupal\Core\Cache\CacheableJsonResponse
73+
*
7174
* @throws \Exception
7275
*/
7376
protected function handleSingle(ServerInterface $server, OperationParams $operation) {
@@ -78,10 +81,13 @@ protected function handleSingle(ServerInterface $server, OperationParams $operat
7881
}
7982

8083
/**
84+
* Execute multiple operations as batch and turn that into cacheable response.
85+
*
8186
* @param \Drupal\graphql\Entity\ServerInterface $server
8287
* @param \GraphQL\Server\OperationParams[] $operations
8388
*
8489
* @return \Drupal\Core\Cache\CacheableJsonResponse
90+
*
8591
* @throws \Exception
8692
*/
8793
protected function handleBatch(ServerInterface $server, array $operations) {

src/Entity/Server.php

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -231,10 +231,10 @@ public function configuration() {
231231
}
232232

233233
/**
234-
* @todo Handle this through configuration (e.g. a context value).
235-
*
236234
* Returns to root value to use when resolving queries against the schema.
237235
*
236+
* @todo Handle this through configuration (e.g. a context value).
237+
*
238238
* May return a callable to resolve the root value at run-time based on the
239239
* provided query parameters / operation.
240240
*
@@ -307,10 +307,10 @@ protected function getContext(SchemaPluginInterface $schema, array $config) {
307307
}
308308

309309
/**
310-
* @todo Handle this through configuration on the server.
311-
*
312310
* Returns the default field resolver.
313311
*
312+
* @todo Handle this through configuration on the server.
313+
*
314314
* Fields that don't explicitly declare a field resolver will use this one
315315
* as a fallback.
316316
*
@@ -353,10 +353,10 @@ protected function getErrorFormatter() {
353353
}
354354

355355
/**
356-
* @todo Handle this through configurable plugins on the server.
357-
*
358356
* Returns the error handler.
359357
*
358+
* @todo Handle this through configurable plugins on the server.
359+
*
360360
* Allows to replace the default error handler with a custom one. For example
361361
* when there is a need to handle specific errors differently.
362362
*
@@ -443,8 +443,6 @@ public function getSortedPersistedQueryInstances() {
443443
}
444444

445445
/**
446-
* @todo Handle this through configurable plugins on the server.
447-
*
448446
* Returns a callable for loading persisted queries.
449447
*
450448
* @return callable
@@ -465,10 +463,10 @@ protected function getPersistedQueryLoader() {
465463
}
466464

467465
/**
468-
* @todo Handle this through configurable plugins on the server.
469-
*
470466
* Returns the validation rules to use for the query.
471467
*
468+
* @todo Handle this through configurable plugins on the server.
469+
*
472470
* May return a callable to allow the server to decide the validation rules
473471
* independently for each query operation.
474472
*

src/Entity/ServerInterface.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,17 @@
1212
interface ServerInterface extends ConfigEntityInterface {
1313

1414
/**
15+
* Execute an operation on this server.
16+
*
1517
* @param \GraphQL\Server\OperationParams $operation
1618
*
1719
* @return \Drupal\graphql\GraphQL\Execution\ExecutionResult
1820
*/
1921
public function executeOperation(OperationParams $operation);
2022

2123
/**
24+
* Execute multiple operations as batch on this server.
25+
*
2226
* @param \GraphQL\Server\OperationParams[] $operations
2327
*
2428
* @return \Drupal\graphql\GraphQL\Execution\ExecutionResult[]

src/Event/OperationEvent.php

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,15 @@ class OperationEvent extends Event {
2626
const GRAPHQL_OPERATION_AFTER = 'graphql.operation.after';
2727

2828
/**
29+
* Result of the query execution.
30+
*
2931
* @var \GraphQL\Executor\ExecutionResult
3032
*/
3133
protected $result;
3234

3335
/**
36+
* Resolver context used for the query.
37+
*
3438
* @var \Drupal\graphql\GraphQL\Execution\ResolveContext
3539
*/
3640
protected $context;
@@ -47,13 +51,17 @@ public function __construct(ResolveContext $context, ExecutionResult $result = N
4751
}
4852

4953
/**
54+
* Returns the execution result.
55+
*
5056
* @return \GraphQL\Executor\ExecutionResult
5157
*/
5258
public function getResult() {
5359
return $this->result;
5460
}
5561

5662
/**
63+
* Returns the resolver context.
64+
*
5765
* @return \Drupal\graphql\GraphQL\Execution\ResolveContext
5866
*/
5967
public function getContext() {

src/EventSubscriber/CurrentLanguageResetTrait.php

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,21 +10,29 @@
1010
trait CurrentLanguageResetTrait {
1111

1212
/**
13+
* The language manager.
14+
*
1315
* @var \Drupal\Core\Language\LanguageManagerInterface
1416
*/
1517
protected $languageManager;
1618

1719
/**
20+
* The language negotiator.
21+
*
1822
* @var \Drupal\language\LanguageNegotiatorInterface
1923
*/
2024
protected $languageNegotiator;
2125

2226
/**
27+
* The translator.
28+
*
2329
* @var \Drupal\Core\StringTranslation\Translator\TranslatorInterface
2430
*/
2531
protected $translator;
2632

2733
/**
34+
* The current user service.
35+
*
2836
* @var \Drupal\Core\Session\AccountInterface
2937
*/
3038
protected $currentUser;

src/Form/PersistedQueriesForm.php

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@
1616
class PersistedQueriesForm extends EntityForm {
1717

1818
/**
19+
* Plugin manager for persisted query plugins.
20+
*
1921
* @var \Drupal\graphql\Plugin\PersistedQueryPluginManager
2022
*/
2123
protected $persistedQueryPluginManager;

src/GraphQL/Buffers/BufferBase.php

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,11 @@ abstract class BufferBase {
2222
protected $results = [];
2323

2424
/**
25+
* Returns the bucket name for grouping items together.
26+
*
2527
* @param object $item
2628
* The item to get the buffer id for.
29+
*
2730
* @return string
2831
* The buffer id.
2932
*/

src/GraphQL/Execution/Executor.php

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,41 +62,57 @@ class Executor implements ExecutorImplementation {
6262
protected $dispatcher;
6363

6464
/**
65+
* The adapter for promises.
66+
*
6567
* @var \GraphQL\Executor\Promise\PromiseAdapter
6668
*/
6769
protected $adapter;
6870

6971
/**
72+
* Represents the GraphQL schema document.
73+
*
7074
* @var \GraphQL\Language\AST\DocumentNode
7175
*/
7276
protected $document;
7377

7478
/**
79+
* The context to pass down during field resolving.
80+
*
7581
* @var \Drupal\graphql\GraphQL\Execution\ResolveContext
7682
*/
7783
protected $context;
7884

7985
/**
86+
* The root of the GraphQL execution tree.
87+
*
8088
* @var mixed
8189
*/
8290
protected $root;
8391

8492
/**
93+
* Variables.
94+
*
8595
* @var array
8696
*/
8797
protected $variables;
8898

8999
/**
100+
* The parsed GraphQL schema.
101+
*
90102
* @var \GraphQL\Type\Schema
91103
*/
92104
protected $schema;
93105

94106
/**
107+
* The operation to be performed.
108+
*
95109
* @var string
96110
*/
97111
protected $operation;
98112

99113
/**
114+
* The resolver to get results for the query.
115+
*
100116
* @var callable
101117
*/
102118
protected $resolver;
@@ -151,6 +167,8 @@ public function __construct(
151167
}
152168

153169
/**
170+
* Constructs an object from a services container.
171+
*
154172
* @param \Symfony\Component\DependencyInjection\ContainerInterface $container
155173
* @param \GraphQL\Executor\Promise\PromiseAdapter $adapter
156174
* @param \GraphQL\Type\Schema $schema
@@ -212,6 +230,8 @@ public function doExecute(): Promise {
212230
}
213231

214232
/**
233+
* Try to return cached results, otherwise resolve the query.
234+
*
215235
* @param string $prefix
216236
*
217237
* @return \GraphQL\Executor\Promise\Promise
@@ -237,6 +257,8 @@ protected function doExecuteCached($prefix) {
237257
}
238258

239259
/**
260+
* Get query results on a cache miss.
261+
*
240262
* @return \GraphQL\Executor\Promise\Promise
241263
*/
242264
protected function doExecuteUncached() {
@@ -263,6 +285,8 @@ protected function doExecuteUncached() {
263285
}
264286

265287
/**
288+
* Calculates the cache prefix from context for the current query.
289+
*
266290
* @return string
267291
*/
268292
protected function cachePrefix() {
@@ -285,6 +309,8 @@ protected function cachePrefix() {
285309
}
286310

287311
/**
312+
* Calculate the cache suffix for the current contexts.
313+
*
288314
* @param array $contexts
289315
*
290316
* @return string
@@ -295,6 +321,8 @@ protected function cacheSuffix(array $contexts = []) {
295321
}
296322

297323
/**
324+
* Lookup cached results by contexts for this query.
325+
*
298326
* @param string $prefix
299327
*
300328
* @return \GraphQL\Executor\ExecutionResult|null
@@ -313,6 +341,8 @@ protected function cacheRead($prefix) {
313341
}
314342

315343
/**
344+
* Store results in cache.
345+
*
316346
* @param string $prefix
317347
* @param \Drupal\graphql\GraphQL\Execution\ExecutionResult $result
318348
*

src/GraphQL/Execution/ExecutorFactory.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@
1313
class ExecutorFactory {
1414

1515
/**
16+
* The service container.
17+
*
1618
* @var \Symfony\Component\DependencyInjection\ContainerInterface
1719
*/
1820
protected $container;
@@ -27,6 +29,8 @@ public function __construct(ContainerInterface $container) {
2729
}
2830

2931
/**
32+
* Factory method to make a new executor.
33+
*
3034
* @param \GraphQL\Executor\Promise\PromiseAdapter $adapter
3135
* @param \GraphQL\Type\Schema $schema
3236
* @param \GraphQL\Language\AST\DocumentNode $document

0 commit comments

Comments
 (0)