Issue #1326664 by Lars Toomre, Albert Volkman, sven.lauer, tim.plunkett: API docs cleanup for parts of system module and other files

core/includes/common.inc

@@ -7160,11 +7160,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_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_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.
  *

core/includes/theme.inc

@@ -715,16 +715,19 @@ 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
  *   An array of available themes.
  * @param $key
  *   The name of the theme whose base we are looking for.
  * @param $used_keys
- *   A recursion parameter preventing endless loops.
+ *   (optional) A recursion parameter preventing endless loops. Defaults to
+ *   NULL.
+ *
  * @return
  *   Returns an array of all of the theme's ancestors; the first element's value
  *   will be NULL if an error occurred.

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().

core/lib/Drupal/Core/Queue/QueueInterface.php

@@ -15,10 +15,10 @@ namespace Drupal\Core\Queue;
  */
 interface QueueInterface {
   /**
-   * Start working with a queue.
+   * Initializes a new queue object.
    *
    * @param $name
-   *   Arbitrary string. The name of the queue to work with.
+   *   An arbitrary string. The name of the queue to work with.
    */
   public function __construct($name);
 

core/modules/system/image.gd.inc

@@ -11,7 +11,19 @@
  */
 
 /**
- * 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 elements returned by this function are integrated into the form
+ * built by system_image_toolkit_settings().
+ *
+ * @return
+ *   An array of Form API elements to be added to the form.
+ *
+ * @see hook_image_toolkits()
+ * @see system_image_toolkit_settings()
  */
 function image_gd_settings() {
   if (image_gd_check_settings()) {
@@ -38,10 +50,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.
+ *   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,7 +70,7 @@ 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
  *   An image object. The $image->resource, $image->info['width'], and
@@ -63,9 +79,11 @@ function image_gd_check_settings() {
  *   The new width of the resized image, in pixels.
  * @param $height
  *   The new height of the resized image, in pixels.
+ *
  * @return
  *   TRUE or FALSE, based on success.
  *
+ * @see hook_image_toolkits()
  * @see image_resize()
  */
 function image_gd_resize(stdClass $image, $width, $height) {
@@ -84,7 +102,7 @@ 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
  *   An image object. The $image->resource, $image->info['width'], and
@@ -92,11 +110,12 @@ function image_gd_resize(stdClass $image, $width, $height) {
  * @param $degrees
  *   The number of (clockwise) degrees to rotate the image.
  * @param $background
- *   An hexadecimal integer specifying the background color to use for the
+ *   (optional) A hexadecimal integer specifying the background color to use
- *   uncovered area of the image after the rotation. E.g. 0x000000 for black,
+ *   for the uncovered area of the image after the rotation. E.g. 0x000000 for
- *   0xff00ff for magenta, and 0xffffff for white. For images that support
+ *   black, 0xff00ff for magenta, and 0xffffff for white. For images that
- *   transparency, this will default to transparent. Otherwise it will
+ *   support transparency, this will default to transparent. Otherwise it will
  *   be white.
+ *
  * @return
  *   TRUE or FALSE, based on success.
  *
@@ -154,7 +173,7 @@ 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
  *   An image object. The $image->resource, $image->info['width'], and
@@ -167,9 +186,11 @@ function image_gd_rotate(stdClass $image, $degrees, $background = NULL) {
  *   The width of the cropped area, in pixels.
  * @param $height
  *   The height of the cropped area, in pixels.
+ *
  * @return
  *   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 +209,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
  *   An image object. The $image->resource value will be modified by this call.
+ *
  * @return
  *   TRUE or FALSE, based on success.
  *
+ * @see hook_image_toolkits()
  * @see image_desaturate()
  */
 function image_gd_desaturate(stdClass $image) {
@@ -210,13 +233,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
  *   An image object. The $image->resource value will populated by this call.
+ *
  * @return
  *   TRUE or FALSE, based on success.
  *
+ * @see hook_image_toolkits()
  * @see image_load()
  */
 function image_gd_load(stdClass $image) {
@@ -238,15 +263,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
  *   An image object.
  * @param $destination
  *   A string file URI or path where the image should be saved.
+ *
  * @return
  *   TRUE or FALSE, based on success.
  *
+ * @see hook_image_toolkits()
  * @see image_save()
  */
 function image_gd_save(stdClass $image, $destination) {
@@ -287,7 +314,7 @@ 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
  *   An image object.
@@ -295,6 +322,7 @@ function image_gd_save(stdClass $image, $destination) {
  *   The new width of the new image, in pixels.
  * @param $height
  *   The new height of the new image, in pixels.
+ *
  * @return
  *   A GD image handle.
  */
@@ -331,9 +359,11 @@ function image_gd_create_tmp(stdClass $image, $width, $height) {
 
 /**
  * Get details about an image.
+ * Image toolkit callback: Retrieves details about an image.
  *
  * @param $image
  *   An image object.
+ *
  * @return
  *   FALSE, if the file could not be found or is not an image. Otherwise, a
  *   keyed array containing information about the image:
@@ -342,6 +372,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) {

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

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) {

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.