Separate short descriptions in docblocks

src/base/ApplicationTrait.php

@@ -1193,6 +1193,7 @@ private function _getUserLanguage(): string
 
     /**
      * Tries to find a language match with the browser's preferred language(s).
+     *
      * If not uses the app's sourceLanguage.
      *
      * @return string

src/base/EagerLoadingFieldInterface.php

@@ -20,6 +20,7 @@ interface EagerLoadingFieldInterface extends SavableComponentInterface
 
     /**
      * Returns an array that maps source-to-target element IDs based on this custom field.
+     *
      * This method aids in the eager-loading of elements when performing an element query. The returned array should
      * contain the following keys:
      * - `elementType` – the fully qualified class name of the element type that should be eager-loaded

src/base/Element.php

@@ -191,6 +191,7 @@ abstract class Element extends Component implements ElementInterface
 
     /**
      * @event ElementStructureEvent The event that is triggered before the element is moved in a structure.
+     *
      * You may set [[ElementStructureEvent::isValid]] to `false` to prevent the element from getting moved.
      */
     const EVENT_BEFORE_MOVE_IN_STRUCTURE = 'beforeMoveInStructure';
@@ -712,6 +713,7 @@ public function __toString()
 
     /**
      * Checks if a property is set.
+     *
      * This method will check if $name is one of the following:
      * - "title"
      * - a magic property supported by [[\yii\base\Component::__isset()]]
@@ -1006,6 +1008,7 @@ public function rules()
 
     /**
      * Calls a custom validation function on a custom field.
+     *
      * This will be called by [[\yii\validators\InlineValidator]] if a custom field specified
      * a closure or the name of a class-level method as the validation type.
      *
@@ -1902,6 +1905,7 @@ protected function normalizeFieldValue(string $fieldHandle)
 
     /**
      * Finds Element instance(s) by the given condition.
+     *
      * This method is internally called by [[findOne()]] and [[findAll()]].
      *
      * @param mixed $criteria Refer to [[findOne()]] and [[findAll()]] for the explanation of this parameter

src/base/ElementInterface.php

@@ -46,6 +46,7 @@ public static function hasTitles(): bool;
 
     /**
      * Returns whether elements of this type can have their own slugs and URIs.
+     *
      * Note that individual elements must also return a URI format from [[getUriFormat()]] if they are to actually get a URI.
      *
      * @return bool Whether elements of this type can have their own slugs and URIs.
@@ -55,6 +56,7 @@ public static function hasUris(): bool;
 
     /**
      * Returns whether elements of this type store content on a per-site basis.
+     *
      * If this returns `true`, the element’s [[getSupportedSites()]] method will
      * be responsible for defining which sites its content should be stored in.
      *
@@ -64,6 +66,7 @@ public static function isLocalized(): bool;
 
     /**
      * Returns whether elements of this type have statuses.
+     *
      * If this returns `true`, the element index template will show a Status menu by default, and your elements will
      * get status indicator icons next to them.
      * Use [[statuses()]] to customize which statuses the elements might have.
@@ -75,6 +78,7 @@ public static function hasStatuses(): bool;
 
     /**
      * Creates an [[ElementQueryInterface]] instance for query purpose.
+     *
      * The returned [[ElementQueryInterface]] instance can be further customized by calling
      * methods defined in [[ElementQueryInterface]] before `one()` or `all()` is called to return
      * populated [[ElementInterface]] instances. For example,
@@ -121,6 +125,7 @@ public static function find(): ElementQueryInterface;
 
     /**
      * Returns a single element instance by a primary key or a set of element criteria parameters.
+     *
      * The method accepts:
      *
      *  - an int: query by a single ID value and return the corresponding element (or null if not found).
@@ -148,6 +153,7 @@ public static function findOne($criteria = null);
 
     /**
      * Returns a list of elements that match the specified ID(s) or a set of element criteria parameters.
+     *
      * The method accepts:
      *
      *  - an int: query by a single ID value and return an array containing the corresponding element
@@ -184,6 +190,7 @@ public static function findAll($criteria = null): array;
 
     /**
      * Returns all of the possible statuses that elements of this type may have.
+     *
      * This method will be called when populating the Status menu on element indexes, for element types whose
      * [[hasStatuses()]] method returns `true`. It will also be called when [[\craft\elements\db\ElementQuery]] is querying for
      * elements, to ensure that its “status” parameter is set to a valid status.
@@ -201,6 +208,7 @@ public static function statuses(): array;
 
     /**
      * Returns the source definitions that elements of this type may belong to.
+     *
      * This defines what will show up in the source list on element indexes and element selector modals.
      * Each item in the array should be set to an array that has the following keys:
      * - **`key`** – The source’s key. This is the string that will be passed into the $source argument of [[actions()]],
@@ -231,6 +239,7 @@ public static function sources(string $context = null): array;
 
     /**
      * Returns the available element actions for a given source (if one is provided).
+     *
      * The actions can either be represented by their class handle (e.g. 'SetStatus'), or by an
      * [[ElementActionInterface]] instance.
      *
@@ -241,6 +250,7 @@ public static function actions(string $source): array;
 
     /**
      * Defines which element attributes should be searchable.
+     *
      * This method should return an array of attribute names that can be accessed on your elements.
      * [[\craft\services\Search]] will call this method when it is indexing keywords for one of your elements,
      * and for each attribute it returns, it will fetch the corresponding property’s value on the element.
@@ -278,6 +288,7 @@ public static function indexHtml(ElementQueryInterface $elementQuery, array $dis
 
     /**
      * Returns the sort options for the element type.
+     *
      * This method should return an array, where the keys reference database column names that should be sorted on,
      * and where the values define the user-facing labels.
      *
@@ -309,6 +320,7 @@ public static function sortOptions(): array;
 
     /**
      * Defines all of the available columns that can be shown in table views.
+     *
      * This method should return an array whose keys map to attribute names and database columns that can be sorted
      * against when querying for elements, and whose values make up the table’s column headers.
      * The *first* item that this array returns will just identify the database column name, and the table column’s
@@ -323,6 +335,7 @@ public static function tableAttributes(): array;
 
     /**
      * Returns the list of table attribute keys that should be shown by default.
+     *
      * This method should return an array where each element in the array maps to one of the keys of the array returned
      * by [[tableAttributes()]].
      *
@@ -333,6 +346,7 @@ public static function defaultTableAttributes(string $source): array;
 
     /**
      * Returns an array that maps source-to-target element IDs based on the given sub-property handle.
+     *
      * This method aids in the eager-loading of elements when performing an element query. The returned array should
      * contain the following keys:
      * - `elementType` – the fully qualified class name of the element type that should be eager-loaded
@@ -366,6 +380,7 @@ public function getFieldLayout();
 
     /**
      * Returns the sites this element is associated with.
+     *
      * The function can either return an array of site IDs, or an array of sub-arrays,
      * each with the keys 'siteId' (int) and 'enabledByDefault' (bool).
      *
@@ -375,6 +390,7 @@ public function getSupportedSites(): array;
 
     /**
      * Returns the URI format used to generate this element’s URI.
+     *
      * Note that element types that can have URIs must return `true` from [[hasUris()]].
      *
      * @return string|null
@@ -720,6 +736,7 @@ public function getHtmlAttributes(string $context): array;
 
     /**
      * Returns the HTML that should be shown for a given attribute in Table View.
+     *
      * This method can be used to completely customize what actually shows up within the table’s body for a given
      * attribute, rather than simply showing the attribute’s raw value.
      * For example, if your elements have an “email” attribute that you want to wrap in a `mailto:` link, your

src/base/FieldInterface.php

@@ -32,6 +32,7 @@ public static function hasContentColumn(): bool;
 
     /**
      * Returns which translation methods the field supports.
+     *
      * This method should return an array with at least one of the following values:
      * - 'none' (values will always be copied to other sites)
      * - 'language' (values will be copied to other sites with the same language)
@@ -48,6 +49,7 @@ public static function supportedTranslationMethods(): array;
 
     /**
      * Returns the column type that this field should get within the content table.
+     *
      * This method will only be called if [[hasContentColumn()]] returns true.
      *
      * @return string The column type. [[\yii\db\QueryBuilder::getColumnType()]] will be called
@@ -60,6 +62,7 @@ public function getContentColumnType(): string;
 
     /**
      * Returns whether the field should be shown as translatable in the UI.
+     *
      * Note this method has no effect on whether the field’s value will get copied over to other
      * sites when the entry is actually getting saved. That is determined by [[getTranslationKey()]].
      *
@@ -70,6 +73,7 @@ public function getIsTranslatable(ElementInterface $element = null): bool;
 
     /**
      * Returns the field’s translation key, based on a given element.
+     *
      * When saving an element on a multi-site Craft install, if `$propagate` is `true` for [[\craft\services\Elements::saveElement()]],
      * then `getTranslationKey()` will be called for each custom field and for each site the element should be propagated to.
      * If the method returns the same value as it did for the initial site, then the initial site’s value will be copied over
@@ -82,6 +86,7 @@ public function getTranslationKey(ElementInterface $element): string;
 
     /**
      * Returns the field’s input HTML.
+     *
      * An extremely simple implementation would be to directly return some HTML:
      *
      * ```php
@@ -172,6 +177,7 @@ public function getInputHtml($value, ElementInterface $element = null): string;
 
     /**
      * Returns a static (non-editable) version of the field’s input HTML.
+     *
      * This function is called to output field values when viewing entry drafts.
      *
      * @param mixed $value The field’s value
@@ -182,6 +188,7 @@ public function getStaticHtml($value, ElementInterface $element): string;
 
     /**
      * Returns the validation rules for an element with this field.
+     *
      * Rules should be defined in the array syntax required by [[\yii\base\Model::rules()]],
      * with one difference: you can skip the first argument (the attribute list).
      * Below are some examples:
@@ -213,6 +220,7 @@ public function isValueEmpty($value, ElementInterface $element): bool;
 
     /**
      * Returns the search keywords that should be associated with this field.
+     *
      * The keywords can be separated by commas and/or whitespace; it doesn’t really matter. [[\craft\services\Search]]
      * will be able to find the individual keywords in whatever string is returned, and normalize them for you.
      *
@@ -224,6 +232,7 @@ public function getSearchKeywords($value, ElementInterface $element): string;
 
     /**
      * Normalizes the field’s value for use.
+     *
      * This method is called when the field’s value is first accessed from the element. For example, the first time
      * `entry.myFieldHandle` is called from a template, or right before [[getInputHtml()]] is called. Whatever
      * this method returns is what `entry.myFieldHandle` will likewise return, and what [[getInputHtml()]]’s and
@@ -237,6 +246,7 @@ public function normalizeValue($value, ElementInterface $element = null);
 
     /**
      * Prepares the field’s value to be stored somewhere, like the content table or JSON-encoded in an entry revision table.
+     *
      * Data types that are JSON-encodable are safe (arrays, integers, strings, booleans, etc).
      * Whatever this returns should be something [[normalizeValue()]] can handle.
      *

src/base/PluginTrait.php

@@ -60,6 +60,7 @@ trait PluginTrait
 
     /**
      * The plugin’s changelog URL.
+     *
      * The URL should begin with `https://` and point to a plain text Markdown-formatted changelog.
      * Version headers must follow the general format:
      *

src/base/SavableComponentInterface.php

@@ -50,6 +50,7 @@ public function validate($attributeNames = null, $clearErrors = true);
 
     /**
      * Returns the list of settings attribute names.
+     *
      * By default, this method returns all public non-static properties that were defined on the called class.
      * You may override this method to change the default behavior.
      *
@@ -67,6 +68,7 @@ public function getSettings(): array;
 
     /**
      * Returns the component’s settings HTML.
+     *
      * An extremely simple implementation would be to directly return some HTML:
      *
      * ```php

src/base/UtilityInterface.php

@@ -20,6 +20,7 @@ interface UtilityInterface extends ComponentInterface
 
     /**
      * Returns the utility’s unique identifier.
+     *
      * The ID should be in `kebab-case`, as it will be visible in the URL (`admin/utilities/the-handle`).
      *
      * @return string
@@ -35,6 +36,7 @@ public static function iconPath();
 
     /**
      * Returns the number that should be shown in the utility’s nav item badge.
+     *
      * If `0` is returned, no badge will be shown
      *
      * @return int

src/behaviors/SessionBehavior.php

@@ -51,6 +51,7 @@ class SessionBehavior extends Behavior
 
     /**
      * Stores a notice in the user’s flash data.
+     *
      * The message will be stored on the session, and can be retrieved by calling
      * [[getFlash()|`getFlash('notice')`]] or [[getAllFlashes()]].
      * Only one flash notice can be stored at a time.
@@ -64,6 +65,7 @@ public function setNotice(string $message)
 
     /**
      * Stores an error message in the user’s flash data.
+     *
      * The message will be stored on the session, and can be retrieved by calling
      * [[getFlash()|`getFlash('error')`]] or [[getAllFlashes()]].
      * Only one flash error message can be stored at a time.
@@ -77,6 +79,7 @@ public function setError(string $message)
 
     /**
      * Queues up an asset bundle to be registered on a future request.
+     *
      * Asset bundles that were queued with this method can be registered using [[getAssetBundleFlashes()]] or
      * [[\craft\web\View::getBodyHtml()]].
      *

src/config/DbConfig.php

@@ -30,6 +30,7 @@ class DbConfig extends BaseObject
 
     /**
      * @var array An array of key => value pairs of PDO attributes to pass into the PDO constructor.
+     *
      * For example, when using the MySQL PDO driver (https://secure.php.net/manual/en/ref.pdo-mysql.php),
      * if you wanted to enable a SSL database connection (assuming SSL is enabled in MySQL
      * (https://dev.mysql.com/doc/refman/5.5/en/using-secure-connections.html) and `'user'`
@@ -58,6 +59,7 @@ class DbConfig extends BaseObject
     public $driver = self::DRIVER_MYSQL;
     /**
      * @var string If you want to manually specify your PDO DSN connection string you can do so here.
+     *
      * - MySQL: https://secure.php.net/manual/en/ref.pdo-mysql.connection.php
      * - PostgreSQL: https://secure.php.net/manual/en/ref.pdo-pgsql.connection.php
      * If you set this, then the [[server]], [[port]], [[user]], [[password]], [[database]],
@@ -96,6 +98,7 @@ class DbConfig extends BaseObject
     public $unixSocket;
     /**
      * @var string|null The database connection URL, if one was provided by your hosting environment.
+     *
      * If this is set, the values for [[driver]], [[user]], [[database]], [[server]], [[port]], and [[database]]
      * will be extracted from it.
      */