From 8ea18442708993bf6c8c273d7e5ea3ee59070c6c Mon Sep 17 00:00:00 2001 From: Lars Toomre Date: Tue, 2 Oct 2012 10:26:47 -0400 Subject: [PATCH] Issue 1326664 by Lars Toomre: Clean up API docs for system module. --- core/includes/common.inc | 6 +- core/includes/theme.inc | 17 ++-- core/lib/Drupal/Core/Mail/PhpMail.php | 2 +- core/lib/Drupal/Core/Queue/QueueInterface.php | 6 +- core/modules/system/image.gd.inc | 112 ++++++++++++------- .../Drupal/system/Tests/Module/DependencyTest.php | 6 +- .../system/Tests/Module/EnableDisableTest.php | 6 +- .../lib/Drupal/system/Tests/Uuid/UuidUnitTest.php | 6 +- core/modules/system/system.admin-rtl.css | 1 + 9 files changed, 98 insertions(+), 64 deletions(-) diff --git a/core/includes/common.inc b/core/includes/common.inc index 6879def..cef7fa4 100644 --- a/core/includes/common.inc +++ b/core/includes/common.inc @@ -7140,11 +7140,11 @@ function drupal_get_filetransfer_info() { * Instantiates and statically caches the correct class for a queue. * * The following variables can be set by variable_set or $conf overrides: - * - queue_class_$name: the class to be used for the queue $name. - * - queue_default_class: the class to use when queue_class_$name is not + * - queue_class_$name: The class to be used for the queue $name. + * - queue_default_class: The class to use when queue_class_$name is not * defined. Defaults to Drupal\Core\Queue\System, a reliable backend using * SQL. - * - queue_default_reliable_class: the class to use when queue_class_$name is + * - queue_default_reliable_class: The class to use when queue_class_$name is * not defined and the queue_default_class is not reliable. Defaults to * Drupal\Core\Queue\System. * diff --git a/core/includes/theme.inc b/core/includes/theme.inc index cb7a84d..db47a0b 100644 --- a/core/includes/theme.inc +++ b/core/includes/theme.inc @@ -714,17 +714,20 @@ function list_themes($refresh = FALSE) { } /** - * Find all the base themes for the specified theme. + * Finds all the base themes for the specified theme. * - * Themes can inherit templates and function implementations from earlier themes. + * Themes can inherit templates and function implementations from earlier + * themes. * - * @param $themes + * @param array $themes * An array of available themes. - * @param $key + * @param string $key * The name of the theme whose base we are looking for. - * @param $used_keys - * A recursion parameter preventing endless loops. - * @return + * @param array $used_keys + * (optional) A recursion parameter preventing endless loops. Defaults to + * NULL. + * + * @return array * Returns an array of all of the theme's ancestors; the first element's value * will be NULL if an error occurred. */ diff --git a/core/lib/Drupal/Core/Mail/PhpMail.php b/core/lib/Drupal/Core/Mail/PhpMail.php index 668cc51..f5ec995 100644 --- a/core/lib/Drupal/Core/Mail/PhpMail.php +++ b/core/lib/Drupal/Core/Mail/PhpMail.php @@ -13,7 +13,7 @@ namespace Drupal\Core\Mail; class PhpMail implements MailInterface { /** - * Concatenates and wrap the e-mail body for plain-text mails. + * Concatenates and wraps the e-mail body for plain-text mails. * * @param array $message * A message array, as described in hook_mail_alter(). diff --git a/core/lib/Drupal/Core/Queue/QueueInterface.php b/core/lib/Drupal/Core/Queue/QueueInterface.php index 90d4b00..ede398e 100644 --- a/core/lib/Drupal/Core/Queue/QueueInterface.php +++ b/core/lib/Drupal/Core/Queue/QueueInterface.php @@ -15,10 +15,10 @@ namespace Drupal\Core\Queue; */ interface QueueInterface { /** - * Start working with a queue. + * Initialize a new queue object. * - * @param $name - * Arbitrary string. The name of the queue to work with. + * @param string $name + * An arbitrary string. The name of the queue to work with. */ public function __construct($name); diff --git a/core/modules/system/image.gd.inc b/core/modules/system/image.gd.inc index f6f12ae..0bb082f 100644 --- a/core/modules/system/image.gd.inc +++ b/core/modules/system/image.gd.inc @@ -11,7 +11,18 @@ */ /** - * Retrieve settings for the GD2 toolkit. + * Image toolkit callback: Returns GD-specific image toolkit settings. + * + * This function verifies that the GD PHP extension is installed. If it is not, + * a form error message is set, informing the user about the missing extension. + * + * The form element returned by this function are integrated into the form + * built by system_image_toolkit_settings(). + * + * @return array + * An array of Form API elements to be added to form. + * + * @see hook_image_toolkits() */ function image_gd_settings() { if (image_gd_check_settings()) { @@ -38,10 +49,14 @@ function image_gd_settings() { } /** - * Verify GD2 settings (that the right version is actually installed). + * Verifies GD2 settings (that the right version is actually installed). * - * @return - * A boolean indicating if the GD toolkit is available on this machine. + * @return bool + * A Boolean indicating whether the correct version of the GD toolkit is + * available on this machine. + * + * @see image_gd_settings() + * @see system_image_toolkits() */ function image_gd_check_settings() { if ($check = get_extension_funcs('gd')) { @@ -54,18 +69,20 @@ function image_gd_check_settings() { } /** - * Scale an image to the specified size using GD. + * Image toolkit callback: Scales an image to the specified size using GD. * - * @param $image + * @param object $image * An image object. The $image->resource, $image->info['width'], and * $image->info['height'] values will be modified by this call. - * @param $width + * @param int $width * The new width of the resized image, in pixels. - * @param $height + * @param int $height * The new height of the resized image, in pixels. - * @return + * + * @return bool * TRUE or FALSE, based on success. * + * @see hook_image_toolkits() * @see image_resize() */ function image_gd_resize(stdClass $image, $width, $height) { @@ -84,20 +101,21 @@ function image_gd_resize(stdClass $image, $width, $height) { } /** - * Rotate an image the given number of degrees. + * Image toolkit callback: Rotates an image a specified number of degrees. * - * @param $image + * @param object $image * An image object. The $image->resource, $image->info['width'], and * $image->info['height'] values will be modified by this call. - * @param $degrees + * @param int $degrees * The number of (clockwise) degrees to rotate the image. - * @param $background - * An hexadecimal integer specifying the background color to use for the - * uncovered area of the image after the rotation. E.g. 0x000000 for black, - * 0xff00ff for magenta, and 0xffffff for white. For images that support - * transparency, this will default to transparent. Otherwise it will + * @param int $background + * (optional) An hexadecimal integer specifying the background color to use + * for the uncovered area of the image after the rotation. E.g. 0x000000 for + * black, 0xff00ff for magenta, and 0xffffff for white. For images that + * support transparency, this will default to transparent. Otherwise it will * be white. - * @return + * + * @return bool * TRUE or FALSE, based on success. * * @see image_rotate() @@ -154,22 +172,24 @@ function image_gd_rotate(stdClass $image, $degrees, $background = NULL) { } /** - * Crop an image using the GD toolkit. + * Image toolkit callback: Crops an image using the GD toolkit. * - * @param $image + * @param object $image * An image object. The $image->resource, $image->info['width'], and * $image->info['height'] values will be modified by this call. - * @param $x + * @param int $x * The starting x offset at which to start the crop, in pixels. - * @param $y + * @param int $y * The starting y offset at which to start the crop, in pixels. - * @param $width + * @param int $width * The width of the cropped area, in pixels. - * @param $height + * @param int $height * The height of the cropped area, in pixels. - * @return + * + * @return bool * TRUE or FALSE, based on success. * + * @see hook_image_toolkits() * @see image_crop() */ function image_gd_crop(stdClass $image, $x, $y, $width, $height) { @@ -188,15 +208,17 @@ function image_gd_crop(stdClass $image, $x, $y, $width, $height) { } /** - * Convert an image resource to grayscale. + * Image toolkit callback: Converts an image to grayscale using the GD toolkit. * * Note that transparent GIFs loose transparency when desaturated. * - * @param $image + * @param object $image * An image object. The $image->resource value will be modified by this call. - * @return + * + * @return bool * TRUE or FALSE, based on success. * + * @see hook_image_toolkits() * @see image_desaturate() */ function image_gd_desaturate(stdClass $image) { @@ -210,13 +232,15 @@ function image_gd_desaturate(stdClass $image) { } /** - * GD helper function to create an image resource from a file. + * Image toolkit callback: Creates a GD image resource from a file. * - * @param $image + * @param object $image * An image object. The $image->resource value will populated by this call. - * @return + * + * @return bool * TRUE or FALSE, based on success. * + * @see hook_image_toolkits() * @see image_load() */ function image_gd_load(stdClass $image) { @@ -238,15 +262,17 @@ function image_gd_load(stdClass $image) { } /** - * GD helper to write an image resource to a destination file. + * Image toolkit callback: Writes an image resource to a destination file. * - * @param $image + * @param object $image * An image object. - * @param $destination + * @param string $destination * A string file URI or path where the image should be saved. - * @return + * + * @return bool * TRUE or FALSE, based on success. * + * @see hook_image_toolkits() * @see image_save() */ function image_gd_save(stdClass $image, $destination) { @@ -287,14 +313,15 @@ function image_gd_save(stdClass $image, $destination) { } /** - * Create a truecolor image preserving transparency from a provided image. + * Creates a truecolor image preserving transparency from a provided image. * - * @param $image + * @param object $image * An image object. - * @param $width + * @param int $width * The new width of the new image, in pixels. - * @param $height + * @param int $height * The new height of the new image, in pixels. + * * @return * A GD image handle. */ @@ -331,10 +358,12 @@ function image_gd_create_tmp(stdClass $image, $width, $height) { /** * Get details about an image. + * Image toolkit callback: Retrieves details about an image. * - * @param $image + * @param object $image * An image object. - * @return + * + * @return array|false * FALSE, if the file could not be found or is not an image. Otherwise, a * keyed array containing information about the image: * - "width": Width, in pixels. @@ -342,6 +371,7 @@ function image_gd_create_tmp(stdClass $image, $width, $height) { * - "extension": Commonly used file extension for the image. * - "mime_type": MIME type ('image/jpeg', 'image/gif', 'image/png'). * + * @see hook_image_toolkits() * @see image_get_info() */ function image_gd_get_info(stdClass $image) { diff --git a/core/modules/system/lib/Drupal/system/Tests/Module/DependencyTest.php b/core/modules/system/lib/Drupal/system/Tests/Module/DependencyTest.php index 88dab0d..c53d225 100644 --- a/core/modules/system/lib/Drupal/system/Tests/Module/DependencyTest.php +++ b/core/modules/system/lib/Drupal/system/Tests/Module/DependencyTest.php @@ -8,7 +8,7 @@ namespace Drupal\system\Tests\Module; /** - * Test module dependency functionality. + * Tests module dependency functionality. */ class DependencyTest extends ModuleTestBase { public static function getInfo() { @@ -20,7 +20,7 @@ class DependencyTest extends ModuleTestBase { } /** - * Attempt to enable translation module without language enabled. + * Attempts to enable translation module without language enabled. */ function testEnableWithoutDependency() { // Attempt to enable content translation without language enabled. @@ -44,7 +44,7 @@ class DependencyTest extends ModuleTestBase { } /** - * Attempt to enable a module with a missing dependency. + * Attempts to enable a module with a missing dependency. */ function testMissingModules() { // Test that the system_dependencies_test module is marked diff --git a/core/modules/system/lib/Drupal/system/Tests/Module/EnableDisableTest.php b/core/modules/system/lib/Drupal/system/Tests/Module/EnableDisableTest.php index cbd26b3..f691e7a 100644 --- a/core/modules/system/lib/Drupal/system/Tests/Module/EnableDisableTest.php +++ b/core/modules/system/lib/Drupal/system/Tests/Module/EnableDisableTest.php @@ -8,7 +8,7 @@ namespace Drupal\system\Tests\Module; /** - * Test module enabling/disabling functionality. + * Tests functionality for enabling and disabling modules. */ class EnableDisableTest extends ModuleTestBase { public static function getInfo() { @@ -20,7 +20,7 @@ class EnableDisableTest extends ModuleTestBase { } /** - * Test that all core modules can be enabled, disabled and uninstalled. + * Tests that all core modules can be enabled, disabled and uninstalled. */ function testEnableDisable() { // Try to enable, disable and uninstall all core modules, unless they are @@ -168,7 +168,7 @@ class EnableDisableTest extends ModuleTestBase { /** * Disables and uninstalls a module and asserts that it was done correctly. * - * @param $module + * @param string $module * The name of the module to disable and uninstall. */ function assertSuccessfulDisableAndUninstall($module) { diff --git a/core/modules/system/lib/Drupal/system/Tests/Uuid/UuidUnitTest.php b/core/modules/system/lib/Drupal/system/Tests/Uuid/UuidUnitTest.php index 94a110b..fb5792b 100644 --- a/core/modules/system/lib/Drupal/system/Tests/Uuid/UuidUnitTest.php +++ b/core/modules/system/lib/Drupal/system/Tests/Uuid/UuidUnitTest.php @@ -37,7 +37,7 @@ class UuidUnitTest extends UnitTestBase { } /** - * Test generating a UUID. + * Tests generating a UUID. */ public function testGenerateUuid() { $uuid = $this->uuid->generate(); @@ -45,7 +45,7 @@ class UuidUnitTest extends UnitTestBase { } /** - * Test that generated UUIDs are unique. + * Tests that generated UUIDs are unique. */ public function testUuidIsUnique() { $uuid1 = $this->uuid->generate(); @@ -54,7 +54,7 @@ class UuidUnitTest extends UnitTestBase { } /** - * Test UUID validation. + * Tests UUID validation. */ function testUuidValidation() { // These valid UUIDs. diff --git a/core/modules/system/system.admin-rtl.css b/core/modules/system/system.admin-rtl.css index d7553b5..2ea4568 100644 --- a/core/modules/system/system.admin-rtl.css +++ b/core/modules/system/system.admin-rtl.css @@ -1,6 +1,7 @@ /** * @file * RTL styles for administration pages. + * Right-to-left-specific stylesheet for System module administration pages. */ /** -- 1.7.6.msysgit.0