Skip to content
GitLab
Commit 7564524a authored by Dries Buytaert's avatar Dries Buytaert
Browse files

Merge branch '8.x' of git.drupal.org:project/drupal into 8.x

parents 593f234f 3b1a495e
Hide whitespace changes
Inline Side-by-side
core/includes/image.inc
View file @ 7564524a
......@@ -34,7 +34,7 @@
*/
/**
* Return a list of available toolkits.
* Gets a list of available toolkits.
*
* @return
* An array with the toolkit names as keys and the descriptions as values.
......@@ -55,7 +55,7 @@ function image_get_available_toolkits() {
}
/**
* Retrieve the name of the currently used toolkit.
* Gets the name of the currently used toolkit.
*
* @return
* String containing the name of the selected toolkit, or FALSE on error.
......@@ -101,7 +101,7 @@ function image_toolkit_invoke($method, stdClass $image, array $params = array())
}
/**
* Get details about an image.
* Gets details about an image.
*
* Drupal supports GIF, JPG and PNG file formats when used with the GD
* toolkit, and may support others, depending on which toolkits are
......@@ -261,7 +261,7 @@ function image_scale(stdClass $image, $width = NULL, $height = NULL, $upscale =
}
/**
* Resize an image to the given dimensions (ignoring aspect ratio).
* Resizes an image to the given dimensions (ignoring aspect ratio).
*
* @param $image
* An image object returned by image_load().
......@@ -284,7 +284,7 @@ function image_resize(stdClass $image, $width, $height) {
}
/**
* Rotate an image by the given number of degrees.
* Rotates an image by the given number of degrees.
*
* @param $image
* An image object returned by image_load().
......@@ -308,7 +308,7 @@ function image_rotate(stdClass $image, $degrees, $background = NULL) {
}
/**
* Crop an image to the rectangle specified by the given rectangle.
* Crops an image to a rectangle specified by the given dimensions.
*
* @param $image
* An image object returned by image_load().
......@@ -340,7 +340,7 @@ function image_crop(stdClass $image, $x, $y, $width, $height) {
}
/**
* Convert an image to grayscale.
* Converts an image to grayscale.
*
* @param $image
* An image object returned by image_load().
......@@ -355,9 +355,8 @@ function image_desaturate(stdClass $image) {
return image_toolkit_invoke('desaturate', $image);
}
/**
* Load an image file and return an image object.
* Loads an image file and returns an image object.
*
* Any changes to the file are not saved until image_save() is called.
*
......@@ -400,7 +399,7 @@ function image_load($file, $toolkit = FALSE) {
}
/**
* Close the image and save the changes to a file.
* Closes the image and saves the changes to a file.
*
* @param $image
* An image object returned by image_load(). The object's 'info' property
......
core/includes/install.core.inc
View file @ 7564524a
......@@ -14,8 +14,7 @@
*/
/**
* Global flag to indicate that a task should not be run during the current
* installation request.
* Do not run the task during the current installation request.
*
* This can be used to skip running an installation task when certain
* conditions are met, even though the task may still show on the list of
......@@ -28,17 +27,14 @@
const INSTALL_TASK_SKIP = 1;
/**
* Global flag to indicate that a task should be run on each installation
* request that reaches it.
* Run the task on each installation request that reaches it.
*
* This is primarily used by the Drupal installer for bootstrap-related tasks.
*/
const INSTALL_TASK_RUN_IF_REACHED = 2;
/**
* Global flag to indicate that a task should be run on each installation
* request that reaches it, until the database is set up and we are able to
* record the fact that it already ran.
* Run the task on each installation request until the database is set up.
*
* This is the default method for running tasks and should be used for most
* tasks that occur after the database is set up; these tasks will then run
......@@ -215,7 +211,7 @@ function install_state_defaults() {
}
/**
* Begin an installation request, modifying the installation state as needed.
* Begins an installation request, modifying the installation state as needed.
*
* This function performs commands that must run at the beginning of every page
* request. It throws an exception if the installation should not proceed.
......@@ -765,7 +761,7 @@ function install_display_output($output, $install_state) {
}
/**
* Installation task; verify the requirements for installing Drupal.
* Verifies the requirements for installing Drupal.
*
* @param $install_state
* An array of information about the current installation state.
......@@ -851,7 +847,7 @@ function install_base_system(&$install_state) {
}
/**
* Verify and return the last installation task that was completed.
* Verifies and returns the last installation task that was completed.
*
* @return
* The last completed task, if there is one. An exception is thrown if Drupal
......@@ -893,7 +889,7 @@ function install_verify_database_settings() {
}
/**
* Verify PDO library.
* Verifies the PDO library.
*/
function install_verify_pdo() {
// PDO was moved to PHP core in 5.2.0, but the old extension (targeting 5.0
......@@ -905,15 +901,13 @@ function install_verify_pdo() {
}
/**
* Installation task; define a form to configure and rewrite settings.php.
* Form constructor for a form to configure and rewrite settings.php.
*
* @param $form_state
* An associative array containing the current state of the form.
* @param $install_state
* An array of information about the current installation state.
*
* @return
* The form API definition for the database configuration form.
* @see install_settings_form_validate()
* @see install_settings_form_submit()
*/
function install_settings_form($form, &$form_state, &$install_state) {
global $databases;
......@@ -975,7 +969,9 @@ function install_settings_form($form, &$form_state, &$install_state) {
}
/**
* Form API validate for install_settings form.
* Form validation handler for install_settings_form().
*
* @see install_settings_form_submit()
*/
function install_settings_form_validate($form, &$form_state) {
$driver = $form_state['values']['driver'];
......@@ -1036,7 +1032,9 @@ function install_database_errors($database, $settings_file) {
}
/**
* Form API submit for install_settings form.
* Form submission handler for install_settings_form().
*
* @see install_settings_form_validate()
*/
function install_settings_form_submit($form, &$form_state) {
global $install_state;
......@@ -1067,7 +1065,7 @@ function install_settings_form_submit($form, &$form_state) {
}
/**
* Installation task; select which profile to install.
* Selects which profile to install.
*
* @param $install_state
* An array of information about the current installation state. The chosen
......@@ -1106,8 +1104,7 @@ function install_select_profile(&$install_state) {
}
/**
* Helper function for automatically selecting an installation profile from a
* list or from a selection passed in via $_POST.
* Selects an installation profile from a list or from a $_POST submission.
*/
function _install_select_profile($profiles) {
// Don't need to choose profile if only one available.
......@@ -1121,7 +1118,7 @@ function _install_select_profile($profiles) {
}
/**
* Form API array definition for the profile selection form.
* Form constructor for the profile selection form.
*
* @param array $install_state
* An array of information about the current installation state.
......@@ -1184,7 +1181,7 @@ function install_select_profile_form($form, &$form_state, $install_state) {
}
/**
* Find all .po files useful for the installer.
* Finds all .po files that are useful to the installer.
*/
function install_find_translations() {
$files = install_find_translation_files();
......@@ -1203,7 +1200,7 @@ function install_find_translations() {
}
/**
* Find installer translations either for a specific langcode or all languages.
* Finds installer translations either for a specific langcode or all languages.
*
* @param $langcode
* (optional) The language code corresponding to the language for which we
......@@ -1223,7 +1220,7 @@ function install_find_translation_files($langcode = NULL) {
}
/**
* Installation task; select which language to use.
* Selects which language to use during installation.
*
* @param $install_state
* An array of information about the current installation state. The chosen
......@@ -1306,7 +1303,7 @@ function install_select_language(&$install_state) {
}
/**
* Form API array definition for language selection.
* Form constructor for the language selection form.
*/
function install_select_language_form($form, &$form_state, $files) {
include_once DRUPAL_ROOT . '/core/includes/standard.inc';
......@@ -1371,7 +1368,7 @@ function install_already_done_error() {
}
/**
* Installation task; load information about the chosen profile.
* Loads information about the chosen profile during installation.
*
* @param $install_state
* An array of information about the current installation state. The loaded
......@@ -1391,7 +1388,7 @@ function install_load_profile(&$install_state) {
}
/**
* Installation task; perform a full bootstrap of Drupal.
* Performs a full bootstrap of Drupal during installation.
*
* @param $install_state
* An array of information about the current installation state.
......@@ -1410,7 +1407,7 @@ function install_bootstrap_full(&$install_state) {
}
/**
* Installation task; install required modules via a batch process.
* Installs required modules via a batch process.
*
* @param $install_state
* An array of information about the current installation state.
......@@ -1463,7 +1460,7 @@ function install_profile_modules(&$install_state) {
}
/**
* Installation task; import languages via a batch process.
* Imports languages via a batch process during installation.
*
* @param $install_state
* An array of information about the current installation state.
......@@ -1504,15 +1501,13 @@ function install_import_translations(&$install_state) {
}
/**
* Installation task; configure settings for the new site.
* Form constructor for a form to configure the new site.
*
* @param $form_state
* An associative array containing the current state of the form.
* @param $install_state
* An array of information about the current installation state.
*
* @return
* The form API definition for the site configuration form.
* @see install_configure_form_validate()
* @see install_configure_form_submit()
*/
function install_configure_form($form, &$form_state, &$install_state) {
drupal_set_title(st('Configure site'));
......@@ -1554,7 +1549,7 @@ function install_configure_form($form, &$form_state, &$install_state) {
}
/**
* Installation task; finish importing files at end of installation.
* Finishes importing files at end of installation.
*
* @param $install_state
* An array of information about the current installation state.
......@@ -1573,7 +1568,7 @@ function install_import_translations_remaining(&$install_state) {
}
/**
* Installation task; perform final steps and display a 'finished' page.
* Performs final installation steps and displays a 'finished' page.
*
* @param $install_state
* An array of information about the current installation state.
......@@ -1758,7 +1753,11 @@ function install_check_requirements($install_state) {
}
/**
* Forms API array definition for site configuration.
* Returns a Forms API array definition for site configuration.
*
* @see install_configure_form()
* @see install_configure_form_validate()
* @see install_configure_form_submit()
*/
function _install_configure_form($form, &$form_state, &$install_state) {
$form['site_information'] = array(
......@@ -1863,7 +1862,9 @@ function _install_configure_form($form, &$form_state, &$install_state) {
}
/**
* Forms API validate for the site configuration form.
* Form validation handler for install_configure_form().
*
* @see install_configure_form_submit()
*/
function install_configure_form_validate($form, &$form_state) {
if ($error = user_validate_name($form_state['values']['account']['name'])) {
......@@ -1872,7 +1873,9 @@ function install_configure_form_validate($form, &$form_state) {
}
/**
* Forms API submit for the site configuration form.
* Form submission handler for install_configure_form().
*
* @see install_configure_form_validate()
*/
function install_configure_form_submit($form, &$form_state) {
global $user;
......
core/includes/install.inc
View file @ 7564524a
<?php
/**
* @file
* API functions for installing modules and themes.
*/
use Drupal\Core\Database\Database;
use Drupal\locale\Gettext;
......@@ -74,7 +79,7 @@
const FILE_NOT_EXECUTABLE = 128;
/**
* Initialize the update system by loading all installed module's .install files.
* Loads .install files for installed modules to initialize the update system.
*/
function drupal_load_updates() {
foreach (drupal_get_installed_schema_version(NULL, FALSE, TRUE) as $module => $schema_version) {
......@@ -109,11 +114,12 @@ function drupal_install_profile_distribution_name() {
}
/**
* Auto detect the base_url with PHP predefined variables.
* Detects the base URL using the PHP $_SERVER variables.
*
* @param $file
* The name of the file calling this function so we can strip it out of
* the URI when generating the base_url.
*
* @return
* The auto-detected $base_url that should be configured in settings.php
*/
......@@ -127,7 +133,7 @@ function drupal_detect_baseurl($file = 'core/install.php') {
}
/**
* Detect all supported databases that are compiled into PHP.
* Detects all supported databases that are compiled into PHP.
*
* @return
* An array of database types compiled into PHP.
......@@ -143,7 +149,7 @@ function drupal_detect_database_types() {
}
/**
* Return all supported database installer objects that are compiled into PHP.
* Returns all supported database installer objects that are compiled into PHP.
*
* @return
* An array of database installer objects compiled into PHP.
......@@ -180,7 +186,7 @@ function drupal_get_database_types() {
}
/**
* Replace values in settings.php with values in the submitted array.
* Replaces values in settings.php with values in the submitted array.
*
* @param $settings
* An array of settings that need to be updated.
......@@ -339,10 +345,11 @@ function install_ensure_config_directory($type) {
}
/**
* Verify an install profile for installation.
* Verifies an install profile for installation.
*
* @param $install_state
* An array of information about the current installation state.
*
* @return
* The list of modules to install.
*/
......@@ -389,7 +396,7 @@ function drupal_verify_profile($install_state) {
}
/**
* Callback to install the system module.
* Installs the system module.
*
* Separated from the installation of other modules so core system
* functions can be made available while other modules are installed.
......@@ -430,7 +437,7 @@ function drupal_install_system() {
}
/**
* Verify the state of the specified file.
* Verifies the state of the specified file.
*
* @param $file
* The file to check for.
......@@ -438,6 +445,7 @@ function drupal_install_system() {
* An optional bitmask created from various FILE_* constants.
* @param $type
* The type of file. Can be file (default), dir, or link.
*
* @return
* TRUE on success or FALSE on failure. A message is set for the latter.
*/
......@@ -509,7 +517,7 @@ function drupal_verify_install_file($file, $mask = NULL, $type = 'file') {
}
/**
* Create a directory with specified permissions.
* Creates a directory with the specified permissions.
*
* @param $file
* The name of the directory to create;
......@@ -517,6 +525,7 @@ function drupal_verify_install_file($file, $mask = NULL, $type = 'file') {
* The permissions of the directory to create.
* @param $message
* (optional) Whether to output messages. Defaults to TRUE.
*
* @return
* TRUE/FALSE whether or not the directory was successfully created.
*/
......@@ -548,7 +557,7 @@ function drupal_install_mkdir($file, $mask, $message = TRUE) {
}
/**
* Attempt to fix file permissions.
* Attempts to fix file permissions.
*
* The general approach here is that, because we do not know the security
* setup of the webserver, we apply our permission changes to all three
......@@ -565,6 +574,7 @@ function drupal_install_mkdir($file, $mask, $message = TRUE) {
* The desired permissions for the file.
* @param $message
* (optional) Whether to output messages. Defaults to TRUE.
*
* @return
* TRUE/FALSE whether or not we were able to fix the file's permissions.
*/
......@@ -630,7 +640,7 @@ function drupal_install_fix_file($file, $mask, $message = TRUE) {
}
/**
* Send the user to a different installer page.
* Sends the user to a different installer page.
*
* This issues an on-site HTTP redirect. Messages (and errors) are erased.
*
......@@ -708,7 +718,7 @@ function drupal_requirements_url($severity) {
}
/**
* Functional equivalent of t(), used when some systems are not available.
* Translates a string when some systems are not available.
*
* Used during the install process, when database, theme, and localization
* system is possibly not yet available.
......@@ -767,7 +777,7 @@ function st($string, array $args = array(), array $options = array()) {
}
/**
* Check an install profile's requirements.
* Checks an install profile's requirements.
*
* @param string $profile
* Name of install profile to check.
......@@ -801,11 +811,12 @@ function drupal_check_profile($profile, array $install_state) {
}
/**
* Extract highest severity from requirements array.
* Extracts the highest severity from the requirements array.
*
* @param $requirements
* An array of requirements, in the same format as is returned by
* hook_requirements().
*
* @return
* The highest severity in the array.
*/
......@@ -820,12 +831,13 @@ function drupal_requirements_severity(&$requirements) {
}
/**
* Check a module's requirements.
* Checks a module's requirements.
*
* @param $module
* Machine name of module to check.
*
* @return
* TRUE/FALSE depending on the requirements are in place.
* TRUE or FALSE, depending on whether the requirements are met.
*/
function drupal_check_module($module) {
module_load_install($module);
......@@ -850,13 +862,14 @@ function drupal_check_module($module) {
}
/**
* Retrieve info about an install profile from its .info file.
* Retrieves information about an install profile from its .info file.
*
* The information stored in a profile .info file is similar to that stored in
* a normal Drupal module .info file. For example:
* - name: The real name of the install profile for display purposes.
* - description: A brief description of the profile.
* - dependencies: An array of shortnames of other modules this install profile requires.
* - dependencies: An array of shortnames of other modules that this install
* profile requires.
*
* Additional, less commonly-used information that can appear in a profile.info
* file but not in a normal Drupal module .info file includes:
......
core/includes/language.inc
View file @ 7564524a
......@@ -479,7 +479,7 @@ function language_from_default() {
}
/**
* Split the given path into prefix and actual path.
* Splits the given path into prefix and actual path.
*
* Parse the given path and return the language object identified by the prefix
* and the actual path.
......@@ -512,10 +512,10 @@ function language_url_split_prefix($path, $languages) {
}
/**
* Return the possible fallback languages ordered by language weight.
* Returns the possible fallback languages ordered by language weight.
*
* @param
* The language type.
* (optional) The language type. Defaults to LANGUAGE_TYPE_CONTENT.
*
* @return
* An array of language codes.
......
core/includes/mail.inc
View file @ 7564524a
......@@ -13,7 +13,7 @@
define('MAIL_LINE_ENDINGS', isset($_SERVER['WINDIR']) || strpos($_SERVER['SERVER_SOFTWARE'], 'Win32') !== FALSE ? "\r\n" : "\n");
/**
* Compose and optionally send an e-mail message.
* Composes and optionally sends an e-mail message.
*
* Sending an e-mail works with defining an e-mail template (subject, text
* and possibly e-mail headers) and the replacement values to use in the
......@@ -195,8 +195,7 @@ function drupal_mail($module, $key, $to, $language, $params = array(), $from = N
}
/**
* Returns an object that implements the Drupal\Core\Mail\MailInterface
* interface.
* Returns an object that implements Drupal\Core\Mail\MailInterface.
*
* Allows for one or more custom mail backends to format and send mail messages
* composed using drupal_mail().
......@@ -291,7 +290,7 @@ function drupal_mail_system($module, $key) {
}
/**
* Perform format=flowed soft wrapping for mail (RFC 3676).
* Performs format=flowed soft wrapping for mail (RFC 3676).
*
* We use delsp=yes wrapping, but only break non-spaced languages when
* absolutely necessary to avoid compatibility issues.
......@@ -334,8 +333,7 @@ function drupal_wrap_mail($text, $indent = '') {
}
/**
* Transform an HTML string into plain text, preserving the structure of the
* markup. Useful for preparing the body of a node to be sent by e-mail.
* Transforms an HTML string into plain text, preserving its structure.
*
* The output will be suitable for use as 'format=flowed; delsp=yes' text
* (RFC 3676) and can be passed directly to drupal_mail() for sending.
......@@ -514,9 +512,9 @@ function drupal_html_to_text($string, $allowed_tags = NULL) {
}
/**
* Helper function for array_walk in drupal_wrap_mail().
*
* Wraps words on a single line.
*
* Callback for array_walk() winthin drupal_wrap_mail().
*/
function _drupal_wrap_mail_line(&$line, $key, $values) {
// Use soft-breaks only for purely quoted or unindented text.
......@@ -526,9 +524,9 @@ function _drupal_wrap_mail_line(&$line, $key, $values) {
}
/**
* Helper function for drupal_html_to_text().
*
* Keeps track of URLs and replaces them with placeholder tokens.
*
* Callback for preg_replace_callback() within drupal_html_to_text().
*/
function _drupal_html_to_mail_urls($match = NULL, $reset = FALSE) {
global $base_url, $base_path;
......@@ -553,18 +551,18 @@ function _drupal_html_to_mail_urls($match = NULL, $reset = FALSE) {
}
/**
* Helper function for drupal_wrap_mail() and drupal_html_to_text().
* Replaces non-quotation markers from a given piece of indentation with spaces.
*
* Replace all non-quotation markers from a given piece of indentation with spaces.
* Callback for array_map() within drupal_html_to_text().
*/
function _drupal_html_to_text_clean($indent) {
return preg_replace('/[^>]/', ' ', $indent);
}
/**
* Helper function for drupal_html_to_text().
* Pads the last line with the given character.
*
* Pad the last line with the given character.
* @see drupal_html_to_text()
*/
function _drupal_html_to_text_pad($text, $pad, $prefix = '') {
// Remove last line break.
......
core/includes/menu.inc
View file @ 7564524a
......@@ -412,9 +412,9 @@ function menu_unserialize($data, $map) {
* @param $path
* The path.
* @param $router_item
* The router item. Usually you take a router entry from menu_get_item and
* set it back either modified or to a different path. This lets you modify the
* navigation block, the page title, the breadcrumb and the page help in one
* The router item. Usually a router entry from menu_get_item() is either
* modified or set to a different path. This allows the navigation block,
* the page title, the breadcrumb, and the page help to be modified in one
* call.
*/
function menu_set_item($path, $router_item) {
......@@ -422,7 +422,7 @@ function menu_set_item($path, $router_item) {
}
/**
* Get a router item.
* Gets a router item.
*