Documentation improvements.

lib/Drupal/views/Tests/ViewStorageTest.php

@@ -13,7 +13,7 @@
 use Drupal\views\Plugin\views\display\Page;
 
 /**
- * Tests that functionality of the the ViewStorageController.
+ * Tests the functionality of the ViewStorageController.
  */
 class ViewStorageTest extends WebTestBase {
 
@@ -207,7 +207,7 @@ protected function deleteTests() {
   }
 
   /**
-   * Tests adding/saving/loading displays on configurables.
+   * Tests adding, saving, and loading displays on configurables.
    */
   protected function displayTests() {
     // Check whether a display can be added and saved to a View.
@@ -218,7 +218,7 @@ protected function displayTests() {
     $new_display = $view->display['test'];
     $this->assertTrue($new_display instanceof ViewDisplay, 'New page display "test" created.');
 
-    // Take sure the right display_plugin is created/instantiated.
+    // Ensure the right display_plugin is created/instantiated.
     $this->assertEqual($new_display->display_plugin, 'page', 'New page display "test" uses the right display plugin.');
     $view->init_display();
     $this->assertTrue($new_display->handler instanceof Page, 'New page display "test" uses the right display plugin.');
@@ -258,11 +258,13 @@ protected function statusTests() {
   }
 
   /**
-   * Load a single Configurable object from the controller.
+   * Loads a single Configurable object from the controller.
    *
    * @param string $view_name
+   *   The machine name of the view.
    *
    * @return object Drupal\views\View.
+   *   The loaded view object.
    */
   protected function loadView($view_name) {
     $load = $this->controller->load(array($view_name));

lib/Drupal/views/ViewDisplay.php

@@ -8,7 +8,7 @@
 namespace Drupal\views;
 
 /**
- * A display type in a view.
+ * Defines a display type in a view.
  *
  * This is just the database storage mechanism, and isn't terribly important
  * to the behavior of the display at all.
@@ -29,8 +29,31 @@ class ViewDisplay {
    */
   public $display_options;
 
-  public function __construct(array $display_options = array()) {
-    $display_options += array(
+  /**
+   * Constructs a ViewDisplay object.
+   *
+   * @param array $values
+   *   An array of display options to set, with the following keys:
+   *   - display_options: (optional) An array of display configuration values.
+   *     Defaults to an empty array.
+   *   - display_plugin: (optional) The display plugin ID, if any. Defaults to
+   *     NULL.
+   *   - id: (optional) The ID of this ViewDisplay object. Defaults to NULL.
+   *   - display_title: (optional) The human-readable label for the display.
+   *     Defaults to an empty string.
+   *   - position: (optional) The weight of the display. Defaults to NULL.
+   *
+   * @todo Determine behavior when values are empty and if these are actually
+   *   optional. Does it make sense to construct a display without an ID or
+   *   plugin?
+   * @todo Rename position to weight.
+   * @todo Rename display_plugin to plugin_id.
+   * @todo Do we actually want to pass these in as an array, or do we want
+   *   explicit parameters or protected properties? (ID, type, array()) is the
+   *   pattern core uses.
+   */
+  public function __construct(array $values = array()) {
+    $values += array(
       'display_options' => array(),
       'display_plugin' => NULL,
       'id' => NULL,
@@ -38,10 +61,10 @@ public function __construct(array $display_options = array()) {
       'position' => NULL,
     );
 
-    $this->display_options = $display_options['display_options'];
-    $this->display_plugin = $display_options['display_plugin'];
-    $this->id = $display_options['id'];
-    $this->display_title = $display_options['display_title'];
+    $this->display_options = $values['display_options'];
+    $this->display_plugin = $values['display_plugin'];
+    $this->id = $values['id'];
+    $this->display_title = $values['display_title'];
   }
 
 }

views.module

@@ -1575,7 +1575,7 @@ function views_get_all_views($reset = FALSE) {
 }
 
 /**
- * Load a view with the storage controller.
+ * Loads a view with the storage controller.
  *
  * @param string $id
  *   The view name to load.
@@ -1590,12 +1590,12 @@ function views_storage_load($id) {
 }
 
 /**
- * Save a view with the storage controller.
+ * Saves a view with the storage controller.
  *
  * @param Drupal\views\View $view
  *   The view which is saved.
  *
- * @return
+ * @return int
  *   SAVED_NEW or SAVED_UPDATED is returned depending on the operation
  *   performed.
  */
@@ -1605,10 +1605,12 @@ function views_storage_save(View $view) {
 }
 
 /**
- * Change the status of a view.
+ * Toggles the view status between enabled and disabled.
  *
  * @param Drupal\views\View $view
  *   The view which gets a different status.
+ * @param bool $status
+ *   Whether to enable or disable the view.
  */
 function views_storage_status(View $view, $status) {
   if (!$status) {
@@ -1716,8 +1718,8 @@ function views_get_views_as_options($views_only = FALSE, $filter = 'all', $exclu
 /**
  * Returns whether the view is enabled.
  *
- * @var Drupal\views\View
- *   The view object of which the status is checked.
+ * @param Drupal\views\View $view
+ *   The view object to check.
  *
  * @return bool
  *   Returns TRUE if a view is enabled, FALSE otherwise.
@@ -1729,8 +1731,8 @@ function views_view_is_enabled($view) {
 /**
  * Returns whether the view is disabled.
  *
- * @var Drupal\views\View
- *   The view object of which the status is checked.
+ * @param Drupal\views\View $view
+ *   The view object to check.
  *
  * @return bool
  *   Returns TRUE if a view is disabled, FALSE otherwise.
@@ -1740,10 +1742,11 @@ function views_view_is_disabled($view) {
 }
 
 /**
- * Get a view from the config.
+ * Loads a view from configuration.
  *
- * @param $name
+ * @param string $name
  *   The name of the view.
+ *
  * @return Drupal\views\View
  *   A reference to the $view object.
  */