Issue #2599524 by blackra, krknth, jhodgdon, rhett.prichard: Fixing order of...

Issue #2599524 by blackra, krknth, jhodgdon, rhett.prichard: Fixing order of documentation sections for /core/lib/Drupal

core/lib/Drupal.php

@@ -120,9 +120,9 @@ public static function unsetContainer() {
   /**
    * Returns the currently active global container.
    *
-   * @throws \Drupal\Core\DependencyInjection\ContainerNotInitializedException
-   *
    * @return \Symfony\Component\DependencyInjection\ContainerInterface|null
+   *
+   * @throws \Drupal\Core\DependencyInjection\ContainerNotInitializedException
    */
   public static function getContainer() {
     if (static::$container === NULL) {
@@ -150,6 +150,7 @@ public static function hasContainer() {
    *
    * @param string $id
    *   The ID of the service to retrieve.
+   *
    * @return mixed
    *   The specified service.
    */

core/lib/Drupal/Component/Plugin/ContextAwarePluginInterface.php

@@ -33,22 +33,22 @@ public function getContextDefinitions();
    * @param string $name
    *   The name of the context in the plugin definition.
    *
-   * @throws \Drupal\Component\Plugin\Exception\PluginException
-   *   If the requested context is not defined.
-   *
    * @return \Drupal\Component\Plugin\Context\ContextDefinitionInterface.
    *   The definition against which the context value must validate.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\PluginException
+   *   If the requested context is not defined.
    */
   public function getContextDefinition($name);
 
   /**
    * Gets the defined contexts.
    *
-   * @throws \Drupal\Component\Plugin\Exception\PluginException
-   *   If contexts are defined but not set.
-   *
    * @return array
    *   The set context objects.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\PluginException
+   *   If contexts are defined but not set.
    */
   public function getContexts();
 
@@ -58,11 +58,11 @@ public function getContexts();
    * @param string $name
    *   The name of the context in the plugin definition.
    *
-   * @throws \Drupal\Component\Plugin\Exception\PluginException
-   *   If the requested context is not set.
-   *
    * @return \Drupal\Component\Plugin\Context\ContextInterface
    *   The context object.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\PluginException
+   *   If the requested context is not set.
    */
   public function getContext($name);
 
@@ -81,11 +81,11 @@ public function getContextValues();
    * @param string $name
    *   The name of the context in the plugin configuration.
    *
-   * @throws \Drupal\Component\Plugin\Exception\PluginException
-   *   If the requested context is not set.
-   *
    * @return mixed
    *   The currently set context value.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\PluginException
+   *   If the requested context is not set.
    */
   public function getContextValue($name);
 
@@ -108,11 +108,11 @@ public function setContext($name, ContextInterface $context);
    *   The value to set the context to. The value has to validate against the
    *   provided context definition.
    *
-   * @throws \Drupal\Component\Plugin\Exception\PluginException
-   *   If the value does not pass validation.
-   *
    * @return \Drupal\Component\Plugin\ContextAwarePluginInterface.
    *   A context aware plugin object for chaining.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\PluginException
+   *   If the value does not pass validation.
    */
   public function setContextValue($name, $value);
 

core/lib/Drupal/Core/Access/AccessManager.php

@@ -155,11 +155,11 @@ public function check(RouteMatchInterface $route_match, AccountInterface $accoun
    * @param \Drupal\Component\Utility\ArgumentsResolverInterface $arguments_resolver
    *   The parametrized arguments resolver instance.
    *
-   * @throws \Drupal\Core\Access\AccessException
-   *   Thrown when the access check returns an invalid value.
-   *
    * @return \Drupal\Core\Access\AccessResultInterface
    *   The access result.
+   *
+   * @throws \Drupal\Core\Access\AccessException
+   *   Thrown when the access check returns an invalid value.
    */
   protected function performCheck($service_id, ArgumentsResolverInterface $arguments_resolver) {
     $callable = $this->checkProvider->loadCheck($service_id);

core/lib/Drupal/Core/Config/ConfigImporter.php

@@ -454,10 +454,10 @@ protected function getUnprocessedExtensions($type) {
   /**
    * Imports the changelist to the target storage.
    *
-   * @throws \Drupal\Core\Config\ConfigException
-   *
    * @return \Drupal\Core\Config\ConfigImporter
    *   The ConfigImporter instance.
+   *
+   * @throws \Drupal\Core\Config\ConfigException
    */
   public function import() {
     if ($this->hasUnprocessedConfigurationChanges()) {
@@ -828,10 +828,10 @@ protected function processExtension($type, $op, $name) {
    * @param string $name
    *   The name of the configuration to process.
    *
-   * @throws \Drupal\Core\Config\ConfigImporterException
-   *
    * @return bool
    *   TRUE is to continue processing, FALSE otherwise.
+   *
+   * @throws \Drupal\Core\Config\ConfigImporterException
    */
   protected function checkOp($collection, $op, $name) {
     if ($op == 'rename') {
@@ -939,13 +939,13 @@ protected function importConfig($collection, $op, $name) {
    * @param string $name
    *   The name of the configuration to process.
    *
-   * @throws \Drupal\Core\Entity\EntityStorageException
-   *   Thrown if the data is owned by an entity type, but the entity storage
-   *   does not support imports.
-   *
    * @return bool
    *   TRUE if the configuration was imported as a configuration entity. FALSE
    *   otherwise.
+   *
+   * @throws \Drupal\Core\Entity\EntityStorageException
+   *   Thrown if the data is owned by an entity type, but the entity storage
+   *   does not support imports.
    */
   protected function importInvokeOwner($collection, $op, $name) {
     // Renames are handled separately.
@@ -989,14 +989,14 @@ protected function importInvokeOwner($collection, $op, $name) {
    *   The rename configuration name, as provided by
    *   \Drupal\Core\Config\StorageComparer::createRenameName().
    *
-   * @throws \Drupal\Core\Entity\EntityStorageException
-   *   Thrown if the data is owned by an entity type, but the entity storage
-   *   does not support imports.
-   *
    * @return bool
    *   TRUE if the configuration was imported as a configuration entity. FALSE
    *   otherwise.
    *
+   * @throws \Drupal\Core\Entity\EntityStorageException
+   *   Thrown if the data is owned by an entity type, but the entity storage
+   *   does not support imports.
+   *
    * @see \Drupal\Core\Config\ConfigImporter::createRenameName()
    */
   protected function importInvokeRename($collection, $rename_name) {

core/lib/Drupal/Core/Config/Schema/TypedConfigInterface.php

@@ -45,11 +45,11 @@ public function getElements();
    *   elements can be get using multiple dot delimited names, for example,
    *   'page.front'.
    *
-   * @throws \InvalidArgumentException
-   *   If an invalid property name is given.
-   *
    * @return \Drupal\Core\TypedData\TypedDataInterface
    *   The property object.
+   *
+   * @throws \InvalidArgumentException
+   *   If an invalid property name is given.
    */
   public function get($name);
 

core/lib/Drupal/Core/DependencyInjection/ClassResolverInterface.php

@@ -20,12 +20,12 @@ interface ClassResolverInterface {
    * @param string $definition
    *   A class name or service name.
    *
-   * @throws \InvalidArgumentException
-   *   If $class is not a valid service identifier and the class does not exist.
-   *
    * @return object
    *   The instance of the class.
-  */
+   *
+   * @throws \InvalidArgumentException
+   *   If $class is not a valid service identifier and the class does not exist.
+   */
   public function getInstanceFromDefinition($definition);
 
 }

core/lib/Drupal/Core/Entity/Enhancer/EntityRouteEnhancer.php

@@ -91,11 +91,11 @@ protected function enhanceEntityList(array $defaults, Request $request) {
    * @param \Symfony\Component\HttpFoundation\Request $request
    *   The Request instance.
    *
-   * @throws \RuntimeException
-   *   Thrown when an entity of a type cannot be found in a route.
-   *
    * @return array
    *   The modified defaults.
+   *
+   * @throws \RuntimeException
+   *   Thrown when an entity of a type cannot be found in a route.
    */
   protected function enhanceEntityView(array $defaults, Request $request) {
     $defaults['_controller'] = '\Drupal\Core\Entity\Controller\EntityViewController::view';

core/lib/Drupal/Core/Entity/EntityAutocompleteMatcher.php

@@ -45,13 +45,13 @@ public function __construct(SelectionPluginManagerInterface $selection_manager)
    * @param string $string
    *   (optional) The label of the entity to query by.
    *
-   * @throws \Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException
-   *   Thrown when the current user doesn't have access to the specifies entity.
-   *
    * @return array
    *   An array of matched entity labels, in the format required by the AJAX
    *   autocomplete API (e.g. array('value' => $value, 'label' => $label)).
    *
+   * @throws \Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException
+   *   Thrown when the current user doesn't have access to the specifies entity.
+   *
    * @see \Drupal\system\Controller\EntityAutocompleteController
    */
   public function getMatches($target_type, $selection_handler, $selection_settings, $string = '') {

core/lib/Drupal/Core/Entity/FieldableEntityInterface.php

@@ -147,11 +147,11 @@ public function toArray();
    * @param string $field_name
    *   The name of the field to get; e.g., 'title' or 'name'.
    *
-   * @throws \InvalidArgumentException
-   *   If an invalid field name is given.
-   *
    * @return \Drupal\Core\Field\FieldItemListInterface
    *   The field item list, containing the field items.
+   *
+   * @throws \InvalidArgumentException
+   *   If an invalid field name is given.
    */
   public function get($field_name);
 
@@ -167,10 +167,10 @@ public function get($field_name);
    *   TRUE. If the update stems from the entity, set it to FALSE to avoid
    *   being notified again.
    *
+   * @return $this
+   *
    * @throws \InvalidArgumentException
    *   If the specified field does not exist.
-   *
-   * @return $this
    */
   public function set($field_name, $value, $notify = TRUE);
 

core/lib/Drupal/Core/Entity/Query/QueryFactoryInterface.php

@@ -35,9 +35,10 @@ public function get(EntityTypeInterface $entity_type, $conjunction);
    *   - AND: all of the conditions on the query need to match.
    *   - OR: at least one of the conditions on the query need to match.
    *
-   * @throws \Drupal\Core\Entity\Query\QueryException
    * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
    *   The query object that can query the given entity type.
+   *
+   * @throws \Drupal\Core\Entity\Query\QueryException
    */
   public function getAggregate(EntityTypeInterface $entity_type, $conjunction);
 

core/lib/Drupal/Core/Entity/Query/Sql/Query.php

@@ -92,11 +92,11 @@ public function execute() {
   /**
    * Prepares the basic query with proper metadata/tags and base fields.
    *
-   * @throws \Drupal\Core\Entity\Query\QueryException
-   *   Thrown if the base table does not exists.
-   *
    * @return \Drupal\Core\Entity\Query\Sql\Query
    *   Returns the called object.
+   *
+   * @throws \Drupal\Core\Entity\Query\QueryException
+   *   Thrown if the base table does not exists.
    */
   protected function prepare() {
     if ($this->allRevisions) {

core/lib/Drupal/Core/Entity/Query/Sql/Tables.php

@@ -235,7 +235,9 @@ public function isFieldCaseSensitive($field_name) {
    * Join entity table if necessary and return the alias for it.
    *
    * @param string $property
+   *
    * @return string
+   *
    * @throws \Drupal\Core\Entity\Query\QueryException
    */
   protected function ensureEntityTable($index_prefix, $property, $type, $langcode, $base_table, $id_field, $entity_tables) {

core/lib/Drupal/Core/Entity/Query/Sql/TablesInterface.php

@@ -23,13 +23,13 @@ interface TablesInterface {
    * @param string $langcode
    *   The language code the field values are to be queried in.
    *
-   * @throws \Drupal\Core\Entity\Query\QueryException
-   *   If $field specifies an invalid relationship.
-   *
    * @return string
    *   The return value is a string containing the alias of the table, a dot
    *   and the appropriate SQL column as passed in. This allows the direct use
    *   of this in a query for a condition or sort.
+   *
+   * @throws \Drupal\Core\Entity\Query\QueryException
+   *   If $field specifies an invalid relationship.
    */
   public function addField($field, $type, $langcode);
 

core/lib/Drupal/Core/Executable/ExecutableManagerInterface.php

@@ -20,12 +20,12 @@ interface ExecutableManagerInterface extends PluginManagerInterface {
    * @param \Drupal\Core\Executable\ExecutableInterface $plugin
    *   An executable plugin instance managed by the implementing manager.
    *
-   * @throws \Drupal\Core\Executable\ExecutableException
-   *   If the plugin could not be executed.
-   *
    * @return mixed
    *   The returned data varies by plugin implementation, e.g. conditions return
    *   the boolean evaluation result.
+   *
+   * @throws \Drupal\Core\Executable\ExecutableException
+   *   If the plugin could not be executed.
    */
   public function execute(ExecutableInterface $plugin);
 

core/lib/Drupal/Core/Extension/module.api.php

@@ -588,17 +588,17 @@ function hook_install_tasks_alter(&$tasks, $install_state) {
  * @param array $sandbox
  *   Stores information for batch updates. See above for more information.
  *
+ * @return string|null
+ *   Optionally, update hooks may return a translated string that will be
+ *   displayed to the user after the update has completed. If no message is
+ *   returned, no message will be presented to the user.
+ *
  * @throws \Drupal\Core\Utility\UpdateException|PDOException
  *   In case of error, update hooks should throw an instance of
  *   Drupal\Core\Utility\UpdateException with a meaningful message for the user.
  *   If a database query fails for whatever reason, it will throw a
  *   PDOException.
  *
- * @return string|null
- *   Optionally, update hooks may return a translated string that will be
- *   displayed to the user after the update has completed. If no message is
- *   returned, no message will be presented to the user.
- *
  * @ingroup update_api
  *
  * @see batch
@@ -683,17 +683,17 @@ function hook_update_N(&$sandbox) {
  * @param array $sandbox
  *   Stores information for batch updates. See above for more information.
  *
+ * @return string|null
+ *   Optionally, hook_post_update_NAME() hooks may return a translated string
+ *   that will be displayed to the user after the update has completed. If no
+ *   message is returned, no message will be presented to the user.
+ *
  * @throws \Drupal\Core\Utility\UpdateException|PDOException
  *   In case of error, update hooks should throw an instance of
  *   \Drupal\Core\Utility\UpdateException with a meaningful message for the
  *   user. If a database query fails for whatever reason, it will throw a
  *   PDOException.
  *
- * @return string|null
- *   Optionally, hook_post_update_NAME() hooks may return a translated string
- *   that will be displayed to the user after the update has completed. If no
- *   message is returned, no message will be presented to the user.
- *
  * @ingroup update_api
  *
  * @see hook_update_N()

core/lib/Drupal/Core/Field/FieldItemInterface.php

@@ -122,11 +122,11 @@ public function getFieldDefinition();
    * @param $property_name
    *   The name of the property to get; e.g., 'title' or 'name'.
    *
-   * @throws \InvalidArgumentException
-   *   If a not existing property is accessed.
-   *
    * @return \Drupal\Core\TypedData\TypedDataInterface
    *   The property object.
+   *
+   * @throws \InvalidArgumentException
+   *   If a not existing property is accessed.
    */
   public function __get($property_name);
 

core/lib/Drupal/Core/Menu/MenuTreeStorageInterface.php

@@ -71,11 +71,11 @@ public function loadMultiple(array $ids);
    * @param array $properties
    *   The properties to filter by.
    *
-   * @throws \InvalidArgumentException
-   *   Thrown if an invalid property name is specified in $properties.
-   *
    * @return array
    *   An array of menu link definition arrays.
+   *
+   * @throws \InvalidArgumentException
+   *   Thrown if an invalid property name is specified in $properties.
    */
   public function loadByProperties(array $properties);
 

core/lib/Drupal/Core/ParamConverter/EntityConverter.php

@@ -101,11 +101,11 @@ public function applies($definition, $name, Route $route) {
    * @param array $defaults
    *   The route defaults array.
    *
-   * @throws \Drupal\Core\ParamConverter\ParamNotConvertedException
-   *   Thrown when the dynamic entity type is not found in the route defaults.
-   *
    * @return string
    *   The entity type ID.
+   *
+   * @throws \Drupal\Core\ParamConverter\ParamNotConvertedException
+   *   Thrown when the dynamic entity type is not found in the route defaults.
    */
   protected function getEntityTypeFromDefaults($definition, $name, array $defaults) {
     $entity_type_id = substr($definition['type'], strlen('entity:'));

core/lib/Drupal/Core/ParamConverter/ParamConverterManagerInterface.php

@@ -54,12 +54,12 @@ public function setRouteParameterConverters(RouteCollection $routes);
    * @param array $defaults
    *   The route defaults array.
    *
+   * @return array
+   *   The modified defaults.
+   *
    * @throws \Drupal\Core\ParamConverter\ParamNotConvertedException
    *   If one of the assigned converters returned NULL because the given
    *   variable could not be converted.
-   *
-   * @return array
-   *   The modified defaults.
    */
   public function convert(array $defaults);
 

core/lib/Drupal/Core/Plugin/ContextAwarePluginInterface.php

@@ -31,11 +31,11 @@ public function getContextDefinitions();
    * @param string $name
    *   The name of the context in the plugin definition.
    *
-   * @throws \Drupal\Component\Plugin\Exception\PluginException
-   *   If the requested context is not defined.
-   *
    * @return \Drupal\Core\Plugin\Context\ContextDefinitionInterface.
    *   The definition against which the context value must validate.
+   *
+   * @throws \Drupal\Component\Plugin\Exception\PluginException
+   *   If the requested context is not defined.
    */
   public function getContextDefinition($name);
 

core/lib/Drupal/Core/Render/RendererInterface.php

@@ -30,10 +30,10 @@ interface RendererInterface {
    * @return \Drupal\Component\Render\MarkupInterface
    *   The rendered HTML.
    *
-   * @see ::render()
-   *
    * @throws \LogicException
    *   When called from inside another renderRoot() call.
+   *
+   * @see ::render()
    */
   public function renderRoot(&$elements);
 
@@ -348,19 +348,19 @@ public function hasRenderContext();
    * Any and all rendering must therefore happen within a render context, and it
    * is this method that provides that.
    *
-   * @see \Drupal\Core\Render\BubbleableMetadata
-   *
    * @param \Drupal\Core\Render\RenderContext $context
    *   The render context to execute the callable within.
    * @param callable $callable
    *   The callable to execute.
+   *
    * @return mixed
    *   The callable's return value.
    *
-   * @see \Drupal\Core\Render\RenderContext
-   *
    * @throws \LogicException
    *   In case bubbling has failed, can only happen in case of broken code.
+   *
+   * @see \Drupal\Core\Render\RenderContext
+   * @see \Drupal\Core\Render\BubbleableMetadata
    */
   public function executeInRenderContext(RenderContext $context, callable $callable);
 

core/lib/Drupal/Core/TypedData/DataDefinitionInterface.php

@@ -43,11 +43,11 @@ interface DataDefinitionInterface {
    * @param string $data_type
    *   The data type, for which a data definition should be created.
    *
+   * @return static
+   *
    * @throws \InvalidArgumentException
    *   If an unsupported data type gets passed to the class; e.g., 'string' to a
    *   definition class handling 'entity:* data types.
-   *
-   * @return static
    */
    public static function createFromDataType($data_type);
 

core/lib/Drupal/Core/TypedData/ListDataDefinitionInterface.php

@@ -35,11 +35,11 @@ interface ListDataDefinitionInterface extends DataDefinitionInterface {
    * @param string $item_type
    *   The item type, for which a list data definition should be created.
    *
+   * @return static
+   *
    * @throws \InvalidArgumentException
    *   If an unsupported data type gets passed to the class; e.g., 'string' to a
    *   definition class handling lists of 'field_item:* data types.
-   *
-   * @return static
    */
   public static function createFromItemType($item_type);
 

core/lib/Drupal/Core/TypedData/TypedDataManagerInterface.php

@@ -122,13 +122,13 @@ public function createListDataDefinition($item_type);
    *   - value: The value to set. If set, it has to match one of the supported
    *     data type formats as documented by the data type classes.
    *
+   * @return \Drupal\Core\TypedData\TypedDataInterface
+   *   The new property instance.
+   *
    * @throws \InvalidArgumentException
    *   If the given property is not known, or the passed object does not
    *   implement the ListInterface or the ComplexDataInterface.
    *
-   * @return \Drupal\Core\TypedData\TypedDataInterface
-   *   The new property instance.
-   *
    * @see \Drupal\Core\TypedData\TypedDataManager::getPropertyInstance()
    */
   public function getInstance(array $options);
@@ -153,13 +153,13 @@ public function getInstance(array $options);
    *   (optional) The data value. If set, it has to match one of the supported
    *   data type formats as documented by the data type classes.
    *
+   * @return \Drupal\Core\TypedData\TypedDataInterface
+   *   The new property instance.
+   *
    * @throws \InvalidArgumentException
    *   If the given property is not known, or the passed object does not
    *   implement the ListInterface or the ComplexDataInterface.
    *
-   * @return \Drupal\Core\TypedData\TypedDataInterface
-   *   The new property instance.
-   *
    * @see \Drupal\Core\TypedData\TypedDataManager::create()
    */
   public function getPropertyInstance(TypedDataInterface $object, $property_name, $value = NULL);