Unverified Commit 914534d3 authored by klausi's avatar klausi Committed by GitHub
Browse files

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

parent c41752fd
......@@ -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>
......
......@@ -64,10 +64,13 @@ class RequestController implements ContainerInjectionInterface {
}
/**
* 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 @@ class RequestController implements ContainerInjectionInterface {
}
/**
* 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) {
......
......@@ -231,10 +231,10 @@ class Server extends ConfigEntityBase implements ServerInterface {
}
/**
* @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 @@ class Server extends ConfigEntityBase implements ServerInterface {
}
/**
* @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 @@ class Server extends ConfigEntityBase implements ServerInterface {
}
/**
* @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 @@ class Server extends ConfigEntityBase implements ServerInterface {
}
/**
* @todo Handle this through configurable plugins on the server.
*
* Returns a callable for loading persisted queries.
*
* @return callable
......@@ -465,10 +463,10 @@ class Server extends ConfigEntityBase implements ServerInterface {
}
/**
* @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.
*
......
......@@ -12,6 +12,8 @@ use GraphQL\Server\OperationParams;
interface ServerInterface extends ConfigEntityInterface {
/**
* Execute an operation on this server.
*
* @param \GraphQL\Server\OperationParams $operation
*
* @return \Drupal\graphql\GraphQL\Execution\ExecutionResult
......@@ -19,6 +21,8 @@ interface ServerInterface extends ConfigEntityInterface {
public function executeOperation(OperationParams $operation);
/**
* Execute multiple operations as batch on this server.
*
* @param \GraphQL\Server\OperationParams[] $operations
*
* @return \Drupal\graphql\GraphQL\Execution\ExecutionResult[]
......
......@@ -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,6 +51,8 @@ class OperationEvent extends Event {
}
/**
* Returns the execution result.
*
* @return \GraphQL\Executor\ExecutionResult
*/
public function getResult() {
......@@ -54,6 +60,8 @@ class OperationEvent extends Event {
}
/**
* Returns the resolver context.
*
* @return \Drupal\graphql\GraphQL\Execution\ResolveContext
*/
public function getContext() {
......
......@@ -10,21 +10,29 @@ use Drupal\language\ConfigurableLanguageManagerInterface;
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;
......
......@@ -16,6 +16,8 @@ use Symfony\Component\DependencyInjection\ContainerInterface;
class PersistedQueriesForm extends EntityForm {
/**
* Plugin manager for persisted query plugins.
*
* @var \Drupal\graphql\Plugin\PersistedQueryPluginManager
*/
protected $persistedQueryPluginManager;
......
......@@ -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.
*/
......
......@@ -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 @@ class Executor implements ExecutorImplementation {
}
/**
* 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 @@ class Executor implements ExecutorImplementation {
}
/**
* Try to return cached results, otherwise resolve the query.
*
* @param string $prefix
*
* @return \GraphQL\Executor\Promise\Promise
......@@ -237,6 +257,8 @@ class Executor implements ExecutorImplementation {
}
/**
* Get query results on a cache miss.
*
* @return \GraphQL\Executor\Promise\Promise
*/
protected function doExecuteUncached() {
......@@ -263,6 +285,8 @@ class Executor implements ExecutorImplementation {
}
/**
* Calculates the cache prefix from context for the current query.
*
* @return string
*/
protected function cachePrefix() {
......@@ -285,6 +309,8 @@ class Executor implements ExecutorImplementation {
}
/**
* Calculate the cache suffix for the current contexts.
*
* @param array $contexts
*
* @return string
......@@ -295,6 +321,8 @@ class Executor implements ExecutorImplementation {
}
/**
* Lookup cached results by contexts for this query.
*
* @param string $prefix
*
* @return \GraphQL\Executor\ExecutionResult|null
......@@ -313,6 +341,8 @@ class Executor implements ExecutorImplementation {
}
/**
* Store results in cache.
*
* @param string $prefix
* @param \Drupal\graphql\GraphQL\Execution\ExecutionResult $result
*
......
......@@ -13,6 +13,8 @@ use Symfony\Component\DependencyInjection\ContainerInterface;
class ExecutorFactory {
/**
* The service container.
*
* @var \Symfony\Component\DependencyInjection\ContainerInterface
*/
protected $container;
......@@ -27,6 +29,8 @@ class ExecutorFactory {
}
/**
* Factory method to make a new executor.
*
* @param \GraphQL\Executor\Promise\PromiseAdapter $adapter
* @param \GraphQL\Type\Schema $schema
* @param \GraphQL\Language\AST\DocumentNode $document
......
......@@ -13,11 +13,15 @@ class FieldContext implements RefinableCacheableDependencyInterface {
use RefinableCacheableDependencyTrait;
/**
* The context that has been passed down.
*
* @var \Drupal\graphql\GraphQL\Execution\ResolveContext
*/
protected $context;
/**
* Schema type information of the current field.
*
* @var \GraphQL\Type\Definition\ResolveInfo
*/
protected $info;
......@@ -35,6 +39,8 @@ class FieldContext implements RefinableCacheableDependencyInterface {
}
/**
* Returns the current field name.
*
* @return string
*/
public function getFieldName() {
......@@ -42,6 +48,8 @@ class FieldContext implements RefinableCacheableDependencyInterface {
}
/**
* Returns the language set as context.
*
* @return string
*/
public function getContextLanguage() {
......@@ -49,6 +57,8 @@ class FieldContext implements RefinableCacheableDependencyInterface {
}
/**
* Sets the context language.
*
* @param string $language
*
* @return $this
......
......@@ -16,36 +16,50 @@ class ResolveContext implements RefinableCacheableDependencyInterface {
use RefinableCacheableDependencyTrait;
/**
* The GraphQL server configuration.
*
* @var \Drupal\graphql\Entity\ServerInterface
*/
protected $server;
/**
* Configuration.
*
* @var array
*/
protected $config;
/**
* List of available contexts keyed by path and context name.
*
* @var array
*/
protected $contexts;
/**
* The operation parameters to perform.
*
* @var \GraphQL\Server\OperationParams
*/
protected $operation;
/**
* The parsed schema document.
*
* @var \GraphQL\Language\AST\DocumentNode
*/
protected $document;
/**
* Type.
*
* @var string
*/
protected $type;
/**
* The context language.
*
* @var string
*/
protected $language;
......@@ -76,6 +90,8 @@ class ResolveContext implements RefinableCacheableDependencyInterface {
}
/**
* Returns the GraphQL server config entity.
*
* @return \Drupal\graphql\Entity\ServerInterface
*/
public function getServer() {
......@@ -83,6 +99,8 @@ class ResolveContext implements RefinableCacheableDependencyInterface {
}
/**
* Returns the current operation parameters.
*
* @return \GraphQL\Server\OperationParams
*/
public function getOperation() {
......@@ -90,6 +108,8 @@ class ResolveContext implements RefinableCacheableDependencyInterface {
}
/**
* Returns the parsed GraphQL schema.
*
* @return \GraphQL\Language\AST\DocumentNode
*/
public function getDocument() {
......@@ -97,6 +117,8 @@ class ResolveContext implements RefinableCacheableDependencyInterface {
}
/**
* Returns the type.
*
* @return string
*/
public function getType(): string {
......@@ -104,6 +126,8 @@ class ResolveContext implements RefinableCacheableDependencyInterface {
}
/**
* Returns the current context language.
*
* @return string
*/
public function getContextLanguage() {
......@@ -111,6 +135,8 @@ class ResolveContext implements RefinableCacheableDependencyInterface {
}
/**
* Sets the current context language.
*
* @param string $language
*
* @return $this
......
......@@ -26,6 +26,8 @@ class ResolverBuilder {
use DataFetcherTrait;
/**
* Instantiate a data producer proxy to lazy resolve a data producer plugin.
*
* @param string $id
* @param array $config
*
......@@ -36,6 +38,8 @@ class ResolverBuilder {
}
/**
* Combine multiple resolvers in a chain resolving after each other.
*
* @param \Drupal\graphql\GraphQL\Resolver\ResolverInterface ...$resolvers
*
* @return \Drupal\graphql\GraphQL\Resolver\Composite
......@@ -45,6 +49,8 @@ class ResolverBuilder {
}
/**
* Register a resolver.
*
* @param \Drupal\graphql\GraphQL\Resolver\ResolverInterface $callback
*
* @return \Drupal\graphql\GraphQL\Resolver\Tap
......@@ -54,6 +60,8 @@ class ResolverBuilder {
}
/**
* Register a resolver for multiple items.
*
* @param \Drupal\graphql\GraphQL\Resolver\ResolverInterface $callback
*
* @return \Drupal\graphql\GraphQL\Resolver\Map
......@@ -63,6 +71,8 @@ class ResolverBuilder {
}
/**
* Register a callback as resolver.
*
* @param callable $callback
*
* @return \Drupal\graphql\GraphQL\Resolver\Callback
......@@ -72,6 +82,8 @@ class ResolverBuilder {
}
/**
* Add a context that is available for further resolvers.
*
* @param string $name
* @param \Drupal\graphql\GraphQL\Resolver\ResolverInterface $source
*
......@@ -83,6 +95,8 @@ class ResolverBuilder {
}
/**
* Add condition branches to resolve.
*
* @param array $branches
*
* @return \Drupal\graphql\GraphQL\Resolver\Condition
......@@ -92,6 +106,8 @@ class ResolverBuilder {
}
/**
* Add a property path resolver.
*
* @param string $type
* @param string $path
* @param \Drupal\graphql\GraphQL\Resolver\ResolverInterface $value
......@@ -106,6 +122,8 @@ class ResolverBuilder {
}
/**
* Adds a fixed value to resolve to.
*
* @param mixed $value
*
* @return \Drupal\graphql\GraphQL\Resolver\Value
......@@ -115,6 +133,8 @@ class ResolverBuilder {
}
/**
* Adds a query argument value to resolve to.
*
* @param string $name
*
* @return \Drupal\graphql\GraphQL\Resolver\Argument
......@@ -124,6 +144,8 @@ class ResolverBuilder {
}
/**
* Resolves the current value that will be a parent for the field.
*
* @return \Drupal\graphql\GraphQL\Resolver\ParentValue
*/
public function fromParent() {
......@@ -131,6 +153,8 @@ class ResolverBuilder {
}
/**
* Resolves a value from the context by context name.
*
* @param string $name
* @param callable|null $default
*
......@@ -141,6 +165,8 @@ class ResolverBuilder {
}
/**
* Adds a default value resolver.
*
* @param mixed $value
* @param mixed $default
*
......