From adaa39ea7a69295f00c2bfa031764c419f21ee51 Mon Sep 17 00:00:00 2001
From: Jennifer Hodgdon <yahgrp@poplarware.com>
Date: Sat, 10 Nov 2012 07:25:19 -0800
Subject: [PATCH] Issue #1313980 by Albert Volkman, Lars Toomre, jn2, xjm:
Massive API docs cleanup for Node module
---
core/modules/node/content_types.inc | 6 +-
core/modules/node/content_types.js | 5 +
.../Drupal/node/Plugin/Core/Entity/Node.php | 6 +-
.../MultiStepNodeFormBasicOptionsTest.php | 4 +-
.../node/Tests/NodeAccessBaseTableTest.php | 13 +-
.../node/Tests/NodeAccessLanguageTest.php | 2 +-
.../node/Tests/NodeAccessRebuildTest.php | 5 +-
.../node/Tests/NodeAccessRecordsTest.php | 4 +-
.../lib/Drupal/node/Tests/NodeAccessTest.php | 8 +-
.../lib/Drupal/node/Tests/NodeAdminTest.php | 4 +-
.../node/Tests/NodeBlockFunctionalTest.php | 2 +-
.../lib/Drupal/node/Tests/NodeBlockTest.php | 3 +
.../node/Tests/NodeBuildContentTest.php | 2 +-
.../Drupal/node/Tests/NodeCreationTest.php | 9 +-
.../lib/Drupal/node/Tests/NodeFeedTest.php | 2 +-
.../Tests/NodeFieldMultilingualTestCase.php | 4 +-
.../node/Tests/NodePostSettingsTest.php | 7 +-
.../Drupal/node/Tests/NodeQueryAlterTest.php | 28 +--
.../Drupal/node/Tests/NodeRSSContentTest.php | 5 +-
.../Drupal/node/Tests/NodeRevisionsTest.php | 5 +-
.../lib/Drupal/node/Tests/NodeSaveTest.php | 8 +-
.../lib/Drupal/node/Tests/NodeTestBase.php | 3 +
.../lib/Drupal/node/Tests/NodeTitleTest.php | 4 +-
.../Drupal/node/Tests/NodeTitleXSSTest.php | 6 +
.../Tests/NodeTypeInitialLanguageTest.php | 4 +-
.../node/Tests/NodeTypePersistenceTest.php | 2 +-
.../lib/Drupal/node/Tests/NodeTypeTest.php | 8 +-
.../lib/Drupal/node/Tests/PageEditTest.php | 7 +-
.../lib/Drupal/node/Tests/PagePreviewTest.php | 7 +-
.../lib/Drupal/node/Tests/PageViewTest.php | 5 +-
.../Drupal/node/Tests/SummaryLengthTest.php | 5 +-
core/modules/node/node.admin.inc | 25 ++-
core/modules/node/node.api.php | 208 +++++++++---------
core/modules/node/node.js | 5 +
core/modules/node/node.module | 88 ++++----
core/modules/node/node.pages.inc | 7 +-
.../node_access_test/node_access_test.module | 4 +-
.../tests/modules/node_test/node_test.module | 6 +-
.../node_test_exception.module | 3 +-
39 files changed, 294 insertions(+), 235 deletions(-)
diff --git a/core/modules/node/content_types.inc b/core/modules/node/content_types.inc
index a6839ae07b3c..999de7ffe240 100644
--- a/core/modules/node/content_types.inc
+++ b/core/modules/node/content_types.inc
@@ -2,7 +2,7 @@
/**
* @file
- * Content type editing UI.
+ * Content type editing user interface.
*/
/**
@@ -426,8 +426,7 @@ function node_node_type_update($info) {
}
/**
- * Resets all of the relevant fields of a module-defined node type to their
- * default values.
+ * Resets relevant fields of a module-defined node type to their default values.
*
* @param $type
* The node type to reset. The node type is passed back by reference with its
@@ -456,6 +455,7 @@ function node_type_reset($type) {
* Form array for delete confirmation form.
*
* @see node_type_delete_confirm_submit()
+ * @ingroup forms
*/
function node_type_delete_confirm($form, &$form_state, $type) {
$form['type'] = array('#type' => 'value', '#value' => $type->type);
diff --git a/core/modules/node/content_types.js b/core/modules/node/content_types.js
index d2a63b6f17a3..736440b522cc 100644
--- a/core/modules/node/content_types.js
+++ b/core/modules/node/content_types.js
@@ -1,3 +1,8 @@
+/**
+ * @file
+ * Javascript for the node content editing form.
+ */
+
(function ($) {
"use strict";
diff --git a/core/modules/node/lib/Drupal/node/Plugin/Core/Entity/Node.php b/core/modules/node/lib/Drupal/node/Plugin/Core/Entity/Node.php
index a9139e9de4f3..1fd8fc8efcd6 100644
--- a/core/modules/node/lib/Drupal/node/Plugin/Core/Entity/Node.php
+++ b/core/modules/node/lib/Drupal/node/Plugin/Core/Entity/Node.php
@@ -154,8 +154,8 @@ class Node extends Entity implements ContentEntityInterface {
/**
* The node promotion status.
*
- * Promoted nodes should be displayed on the front page of the site. The
- * value is either NODE_PROMOTED or NODE_NOT_PROMOTED.
+ * Promoted nodes should be displayed on the front page of the site. The value
+ * is either NODE_PROMOTED or NODE_NOT_PROMOTED.
*
* @var integer
*/
@@ -184,7 +184,7 @@ class Node extends Entity implements ContentEntityInterface {
/**
* The node translation status.
*
- * If the translation page needs to be updated the value is 1, otherwise 0.
+ * If the translation page needs to be updated, the value is 1; otherwise 0.
*
* @var integer
*/
diff --git a/core/modules/node/lib/Drupal/node/Tests/MultiStepNodeFormBasicOptionsTest.php b/core/modules/node/lib/Drupal/node/Tests/MultiStepNodeFormBasicOptionsTest.php
index abb31f379dc3..873c7ea98541 100644
--- a/core/modules/node/lib/Drupal/node/Tests/MultiStepNodeFormBasicOptionsTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/MultiStepNodeFormBasicOptionsTest.php
@@ -10,7 +10,7 @@
use Drupal\simpletest\WebTestBase;
/**
- * Test multistep node forms basic options.
+ * Tests basic options of multi-step node forms.
*/
class MultiStepNodeFormBasicOptionsTest extends WebTestBase {
@@ -37,7 +37,7 @@ function setUp() {
}
/**
- * Change the default values of basic options to ensure they persist.
+ * Tests changing the default values of basic options to ensure they persist.
*/
function testMultiStepNodeFormBasicOptions() {
$edit = array(
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeAccessBaseTableTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeAccessBaseTableTest.php
index eb4524d19c0e..6b7d00deb239 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeAccessBaseTableTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeAccessBaseTableTest.php
@@ -19,7 +19,13 @@ class NodeAccessBaseTableTest extends NodeTestBase {
*/
public static $modules = array('node_access_test');
- // Requires tags taxonomy field.
+ /**
+ * The installation profile to use with this test.
+ *
+ * This test class requires the "tags" taxonomy field.
+ *
+ * @var string
+ */
protected $profile = 'standard';
public static function getInfo() {
@@ -30,9 +36,6 @@ public static function getInfo() {
);
}
- /**
- * Enable modules and create user with specific permissions.
- */
public function setUp() {
parent::setUp();
@@ -41,7 +44,7 @@ public function setUp() {
}
/**
- * Test the "private" node access.
+ * Tests the "private" node access functionality.
*
* - Create 2 users with "access content" and "create article" permissions.
* - Each user creates one private and one not private article.
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeAccessLanguageTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeAccessLanguageTest.php
index 021e22804dd0..6ff6ae084fc0 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeAccessLanguageTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeAccessLanguageTest.php
@@ -10,7 +10,7 @@
use Drupal\Core\Language\Language;
/**
- * Test case to verify node_access functionality for multiple languages.
+ * Verifies node_access() functionality for multiple languages.
*/
class NodeAccessLanguageTest extends NodeTestBase {
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeAccessRebuildTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeAccessRebuildTest.php
index 612ba362c4ef..379397e8c1bf 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeAccessRebuildTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeAccessRebuildTest.php
@@ -8,7 +8,7 @@
namespace Drupal\node\Tests;
/**
- * Rebuild the node_access table.
+ * Verifies the rebuild functionality for the node_access table.
*/
class NodeAccessRebuildTest extends NodeTestBase {
public static function getInfo() {
@@ -27,6 +27,9 @@ function setUp() {
$this->web_user = $web_user;
}
+ /**
+ * Tests rebuilding the node access permissions table.
+ */
function testNodeAccessRebuild() {
$this->drupalGet('admin/reports/status');
$this->clickLink(t('Rebuild permissions'));
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeAccessRecordsTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeAccessRecordsTest.php
index 3bbce9c366e9..e2b4c07b4434 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeAccessRecordsTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeAccessRecordsTest.php
@@ -8,7 +8,7 @@
namespace Drupal\node\Tests;
/**
- * Test case to verify hook_node_access_records functionality.
+ * Tests hook_node_access_records() functionality.
*/
class NodeAccessRecordsTest extends NodeTestBase {
@@ -28,7 +28,7 @@ public static function getInfo() {
}
/**
- * Create a node and test the creation of node access rules.
+ * Creates a node and tests the creation of node access rules.
*/
function testNodeAccessRecords() {
// Create an article node.
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeAccessTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeAccessTest.php
index 0c784ae0fc1a..4f87348738e2 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeAccessTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeAccessTest.php
@@ -8,9 +8,11 @@
namespace Drupal\node\Tests;
/**
- * Test case to verify basic node_access functionality.
+ * Tests basic node_access functionality.
+ *
+ * Note that hook_node_access_records() is covered in another test class.
+ *
* @todo Cover hook_node_access in a separate test class.
- * hook_node_access_records is covered in another test class.
*/
class NodeAccessTest extends NodeTestBase {
public static function getInfo() {
@@ -22,7 +24,7 @@ public static function getInfo() {
}
/**
- * Asserts node_access correctly grants or denies access.
+ * Asserts node_access() correctly grants or denies access.
*/
function assertNodeAccess($ops, $node, $account) {
foreach ($ops as $op => $result) {
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeAdminTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeAdminTest.php
index 3c027657da32..bcfbfcdedd45 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeAdminTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeAdminTest.php
@@ -8,9 +8,10 @@
namespace Drupal\node\Tests;
/**
- * Test node administration page functionality.
+ * Tests node administration page functionality.
*/
class NodeAdminTest extends NodeTestBase {
+
public static function getInfo() {
return array(
'name' => 'Node administration',
@@ -76,6 +77,7 @@ function testContentAdminSort() {
* Tests content overview with different user permissions.
*
* Taxonomy filters are tested separately.
+ *
* @see TaxonomyNodeFilterTestCase
*/
function testContentAdminPages() {
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeBlockFunctionalTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeBlockFunctionalTest.php
index edcb0075bd68..46b003f18046 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeBlockFunctionalTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeBlockFunctionalTest.php
@@ -36,7 +36,7 @@ function setUp() {
}
/**
- * Test the recent comments block.
+ * Tests the recent comments block.
*/
function testRecentNodeBlock() {
$this->drupalLogin($this->admin_user);
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeBlockTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeBlockTest.php
index 674bae13828a..0b9adb2691bd 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeBlockTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeBlockTest.php
@@ -7,6 +7,9 @@
namespace Drupal\node\Tests;
+/**
+ * Tests the availability of the syndicate block.
+ */
class NodeBlockTest extends NodeTestBase {
/**
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeBuildContentTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeBuildContentTest.php
index 7ac8685f4c87..ac560419f8c6 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeBuildContentTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeBuildContentTest.php
@@ -21,7 +21,7 @@ public static function getInfo() {
}
/**
- * Test to ensure that a node's content array is rebuilt on every call to node_build_content().
+ * Ensures that content array is rebuilt on every call to node_build_content().
*/
function testNodeRebuildContent() {
$node = $this->drupalCreateNode();
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeCreationTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeCreationTest.php
index 285e616dc245..36baad256d5d 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeCreationTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeCreationTest.php
@@ -10,6 +10,9 @@
use Drupal\Core\Database\Database;
use Exception;
+/**
+ * Tests creating and saving a node.
+ */
class NodeCreationTest extends NodeTestBase {
/**
@@ -37,7 +40,7 @@ function setUp() {
}
/**
- * Create a "Basic page" node and verify its consistency in the database.
+ * Creates a "Basic page" node and verifies its consistency in the database.
*/
function testNodeCreation() {
// Create a node.
@@ -56,7 +59,7 @@ function testNodeCreation() {
}
/**
- * Create a page node and verify that a transaction rolls back the failed creation
+ * Verifies that a transaction rolls back the failed creation.
*/
function testFailedPageCreation() {
// Create a node.
@@ -97,7 +100,7 @@ function testFailedPageCreation() {
}
/**
- * Create an unpublished node and confirm correct redirect behavior.
+ * Creates an unpublished node and confirms correct redirect behavior.
*/
function testUnpublishedNodeCreation() {
// Set the front page to the test page.
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeFeedTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeFeedTest.php
index ca660e445396..0fd06d1b5d7e 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeFeedTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeFeedTest.php
@@ -22,7 +22,7 @@ public static function getInfo() {
}
/**
- * Ensure that node_feed accepts and prints extra channel elements.
+ * Ensures that node_feed() accepts and prints extra channel elements.
*/
function testNodeFeedExtraChannelElements() {
$response = node_feed(array(), array('copyright' => 'Drupal is a registered trademark of Dries Buytaert.'));
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeFieldMultilingualTestCase.php b/core/modules/node/lib/Drupal/node/Tests/NodeFieldMultilingualTestCase.php
index 9c3dd064fa96..ffe03329cda6 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeFieldMultilingualTestCase.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeFieldMultilingualTestCase.php
@@ -65,7 +65,7 @@ function setUp() {
}
/**
- * Test if field languages are correctly set through the node form.
+ * Tests whether field languages are correctly set through the node form.
*/
function testMultilingualNodeForm() {
// Create "Basic page" content.
@@ -113,7 +113,7 @@ function testMultilingualNodeForm() {
}
/*
- * Test multilingual field display settings.
+ * Tests multilingual field display settings.
*/
function testMultilingualDisplaySettings() {
// Create "Basic page" content.
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodePostSettingsTest.php b/core/modules/node/lib/Drupal/node/Tests/NodePostSettingsTest.php
index 375d50f520f4..ce4861491f27 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodePostSettingsTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodePostSettingsTest.php
@@ -8,9 +8,10 @@
namespace Drupal\node\Tests;
/**
- * Check that the post information displays when enabled for a content type.
+ * Checks that the post information displays when enabled for a content type.
*/
class NodePostSettingsTest extends NodeTestBase {
+
public static function getInfo() {
return array(
'name' => 'Node post information display',
@@ -27,7 +28,7 @@ function setUp() {
}
/**
- * Set "Basic page" content type to display post information and confirm its presence on a new node.
+ * Confirms "Basic page" content type and post information is on a new node.
*/
function testPagePostInfo() {
@@ -50,7 +51,7 @@ function testPagePostInfo() {
}
/**
- * Set "Basic page" content type to not display post information and confirm its absence on a new node.
+ * Confirms absence of post information on a new node.
*/
function testPageNotPostInfo() {
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeQueryAlterTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeQueryAlterTest.php
index 592ab99f3033..cb2b329c1d83 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeQueryAlterTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeQueryAlterTest.php
@@ -83,10 +83,10 @@ function testNodeQueryAlterWithUI() {
}
/**
- * Lower-level test of 'node_access' query alter, for user with access.
+ * Tests 'node_access' query alter, for user with access.
*
- * Verifies that a non-standard table alias can be used, and that a
- * user with node access can view the nodes.
+ * Verifies that a non-standard table alias can be used, and that a user with
+ * node access can view the nodes.
*/
function testNodeQueryAlterLowLevelWithAccess() {
// User with access should be able to view 4 nodes.
@@ -106,10 +106,10 @@ function testNodeQueryAlterLowLevelWithAccess() {
}
/**
- * Lower-level test of 'node_access' query alter, for user without access.
+ * Tests 'node_access' query alter, for user without access.
*
- * Verifies that a non-standard table alias can be used, and that a
- * user without node access cannot view the nodes.
+ * Verifies that a non-standard table alias can be used, and that a user
+ * without node access cannot view the nodes.
*/
function testNodeQueryAlterLowLevelNoAccess() {
// User without access should be able to view 0 nodes.
@@ -129,10 +129,10 @@ function testNodeQueryAlterLowLevelNoAccess() {
}
/**
- * Lower-level test of 'node_access' query alter, for edit access.
+ * Tests 'node_access' query alter, for edit access.
*
- * Verifies that a non-standard table alias can be used, and that a
- * user with view-only node access cannot edit the nodes.
+ * Verifies that a non-standard table alias can be used, and that a user with
+ * view-only node access cannot edit the nodes.
*/
function testNodeQueryAlterLowLevelEditAccess() {
// User with view-only access should not be able to edit nodes.
@@ -154,13 +154,13 @@ function testNodeQueryAlterLowLevelEditAccess() {
}
/**
- * Lower-level test of 'node_access' query alter override.
+ * Tests 'node_access' query alter override.
*
* Verifies that node_access_view_all_nodes() is called from
- * node_query_node_access_alter(). We do this by checking that
- * a user which normally would not have view privileges is able
- * to view the nodes when we add a record to {node_access} paired
- * with a corresponding privilege in hook_node_grants().
+ * node_query_node_access_alter(). We do this by checking that a user who
+ * normally would not have view privileges is able to view the nodes when we
+ * add a record to {node_access} paired with a corresponding privilege in
+ * hook_node_grants().
*/
function testNodeQueryAlterOverride() {
$record = array(
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeRSSContentTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeRSSContentTest.php
index 8ca8f0523d97..1e0adfb0898a 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeRSSContentTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeRSSContentTest.php
@@ -8,7 +8,7 @@
namespace Drupal\node\Tests;
/**
- * Ensure that data added to nodes by other modules appears in RSS feeds.
+ * Ensures that data added to nodes by other modules appears in RSS feeds.
*
* Create a node, enable the node_test module to ensure that extra data is
* added to the node->content array, then verify that the data appears on the
@@ -42,8 +42,7 @@ function setUp() {
}
/**
- * Create a new node and ensure that it includes the custom data when added
- * to an RSS feed.
+ * Ensures that a new node includes the custom data when added to an RSS feed.
*/
function testNodeRSSContent() {
// Create a node.
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeRevisionsTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeRevisionsTest.php
index 6bb752fa6b1d..877c003f50d0 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeRevisionsTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeRevisionsTest.php
@@ -7,6 +7,9 @@
namespace Drupal\node\Tests;
+/**
+ * Tests the node revision functionality.
+ */
class NodeRevisionsTest extends NodeTestBase {
protected $nodes;
protected $logs;
@@ -58,7 +61,7 @@ function setUp() {
}
/**
- * Check node revision related operations.
+ * Checks node revision related operations.
*/
function testRevisions() {
$nodes = $this->nodes;
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeSaveTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeSaveTest.php
index ba2113c7a15e..f86bc522c1ad 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeSaveTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeSaveTest.php
@@ -8,7 +8,7 @@
namespace Drupal\node\Tests;
/**
- * Test case to check node save related functionality, including import-save
+ * Tests node save related functionality, including import-save.
*/
class NodeSaveTest extends NodeTestBase {
@@ -37,7 +37,8 @@ function setUp() {
}
/**
- * Import test, to check if custom node ids are saved properly.
+ * Checks whether custom node IDs are saved properly during an import operation.
+ *
* Workflow:
* - first create a piece of content
* - save the content
@@ -71,8 +72,7 @@ function testImport() {
}
/**
- * Check that the "created" and "changed" timestamps are set correctly when
- * saving a new node or updating an existing node.
+ * Verifies accuracy of the "created" and "changed" timestamp functionality.
*/
function testTimestamps() {
// Use the default timestamps.
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeTestBase.php b/core/modules/node/lib/Drupal/node/Tests/NodeTestBase.php
index 3c3927920ee6..1bba55800679 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeTestBase.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeTestBase.php
@@ -9,6 +9,9 @@
use Drupal\simpletest\WebTestBase;
+/**
+ * Sets up page and article content types.
+ */
abstract class NodeTestBase extends WebTestBase {
/**
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeTitleTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeTitleTest.php
index 1880d4f9d262..e657d762f7b7 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeTitleTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeTitleTest.php
@@ -8,7 +8,7 @@
namespace Drupal\node\Tests;
/**
- * Test node title.
+ * Tests node title functionality.
*/
class NodeTitleTest extends NodeTestBase {
@@ -37,7 +37,7 @@ function setUp() {
}
/**
- * Create one node and test if the node title has the correct value.
+ * Creates one node and tests if the node title has the correct value.
*/
function testNodeTitle() {
// Create "Basic page" content with title.
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeTitleXSSTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeTitleXSSTest.php
index af30e19d4bb1..8810f79953a3 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeTitleXSSTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeTitleXSSTest.php
@@ -7,6 +7,9 @@
namespace Drupal\node\Tests;
+/**
+ * Tests XSS functionality with a node entity.
+ */
class NodeTitleXSSTest extends NodeTestBase {
public static function getInfo() {
return array(
@@ -16,6 +19,9 @@ public static function getInfo() {
);
}
+ /**
+ * Tests XSS functionality with a node entity.
+ */
function testNodeTitleXSS() {
// Prepare a user to do the stuff.
$web_user = $this->drupalCreateUser(array('create page content', 'edit any page content'));
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeTypeInitialLanguageTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeTypeInitialLanguageTest.php
index 4a8508550ab7..5c906d79d248 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeTypeInitialLanguageTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeTypeInitialLanguageTest.php
@@ -35,7 +35,7 @@ function setUp() {
}
/**
- * Tests the node type initial language defaults, and modify them.
+ * Tests the node type initial language defaults, and modifies them.
*
* The default initial language must be the site's default, and the language
* locked option must be on.
@@ -95,7 +95,7 @@ function testNodeTypeInitialLanguageDefaults() {
}
/**
- * Tests Language field visibility features.
+ * Tests language field visibility features.
*/
function testLanguageFieldVisibility() {
$langcode = LANGUAGE_NOT_SPECIFIED;
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeTypePersistenceTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeTypePersistenceTest.php
index c67f01afba73..c51b5a0b7bd7 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeTypePersistenceTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeTypePersistenceTest.php
@@ -20,7 +20,7 @@ public static function getInfo() {
}
/**
- * Test node type customizations persist through disable and uninstall.
+ * Tests that node type customizations persist through disable and uninstall.
*/
function testNodeTypeCustomizationPersistence() {
$web_user = $this->drupalCreateUser(array('bypass node access', 'administer content types', 'administer modules'));
diff --git a/core/modules/node/lib/Drupal/node/Tests/NodeTypeTest.php b/core/modules/node/lib/Drupal/node/Tests/NodeTypeTest.php
index f4e758ac3c3d..944af151aa18 100644
--- a/core/modules/node/lib/Drupal/node/Tests/NodeTypeTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/NodeTypeTest.php
@@ -28,7 +28,7 @@ public static function getInfo() {
}
/**
- * Ensure that node type functions (node_type_get_*) work correctly.
+ * Ensures that node type functions (node_type_get_*) work correctly.
*
* Load available node types and validate the returned data.
*/
@@ -47,7 +47,7 @@ function testNodeTypeGetFunctions() {
}
/**
- * Test creating a content type programmatically and via a form.
+ * Tests creating a content type programmatically and via a form.
*/
function testNodeTypeCreation() {
// Create a content type programmaticaly.
@@ -77,7 +77,7 @@ function testNodeTypeCreation() {
}
/**
- * Test editing a node type using the UI.
+ * Tests editing a node type using the UI.
*/
function testNodeTypeEditing() {
$web_user = $this->drupalCreateUser(array('bypass node access', 'administer content types'));
@@ -130,7 +130,7 @@ function testNodeTypeEditing() {
}
/**
- * Test that node_types_rebuild() correctly handles the 'disabled' flag.
+ * Tests that node_types_rebuild() correctly handles the 'disabled' flag.
*/
function testNodeTypeStatus() {
// Enable all core node modules, and all types should be active.
diff --git a/core/modules/node/lib/Drupal/node/Tests/PageEditTest.php b/core/modules/node/lib/Drupal/node/Tests/PageEditTest.php
index 8d4e0fea42c9..20ebfbd48656 100644
--- a/core/modules/node/lib/Drupal/node/Tests/PageEditTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/PageEditTest.php
@@ -7,6 +7,9 @@
namespace Drupal\node\Tests;
+/**
+ * Tests the node edit functionality.
+ */
class PageEditTest extends NodeTestBase {
protected $web_user;
protected $admin_user;
@@ -27,7 +30,7 @@ function setUp() {
}
/**
- * Check node edit functionality.
+ * Checks node edit functionality.
*/
function testPageEdit() {
$this->drupalLogin($this->web_user);
@@ -94,7 +97,7 @@ function testPageEdit() {
}
/**
- * Check changing node authored by fields.
+ * Tests changing a node's "authored by" field.
*/
function testPageAuthoredBy() {
$this->drupalLogin($this->admin_user);
diff --git a/core/modules/node/lib/Drupal/node/Tests/PagePreviewTest.php b/core/modules/node/lib/Drupal/node/Tests/PagePreviewTest.php
index 81e492e188ee..b429e07df407 100644
--- a/core/modules/node/lib/Drupal/node/Tests/PagePreviewTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/PagePreviewTest.php
@@ -7,6 +7,9 @@
namespace Drupal\node\Tests;
+/**
+ * Tests the node entity preview functionality.
+ */
class PagePreviewTest extends NodeTestBase {
public static function getInfo() {
return array(
@@ -24,7 +27,7 @@ function setUp() {
}
/**
- * Check the node preview functionality.
+ * Checks the node preview functionality.
*/
function testPagePreview() {
$langcode = LANGUAGE_NOT_SPECIFIED;
@@ -48,7 +51,7 @@ function testPagePreview() {
}
/**
- * Check the node preview functionality, when using revisions.
+ * Checks the node preview functionality, when using revisions.
*/
function testPagePreviewWithRevisions() {
$langcode = LANGUAGE_NOT_SPECIFIED;
diff --git a/core/modules/node/lib/Drupal/node/Tests/PageViewTest.php b/core/modules/node/lib/Drupal/node/Tests/PageViewTest.php
index 460eb25c5817..deab20a0340a 100644
--- a/core/modules/node/lib/Drupal/node/Tests/PageViewTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/PageViewTest.php
@@ -7,6 +7,9 @@
namespace Drupal\node\Tests;
+/**
+ * Tests the functionality of node entity edit permissions.
+ */
class PageViewTest extends NodeTestBase {
public static function getInfo() {
return array(
@@ -17,7 +20,7 @@ public static function getInfo() {
}
/**
- * Creates a node and then an anonymous and unpermissioned user attempt to edit the node.
+ * Tests an anonymous and unpermissioned user attempting to edit the node.
*/
function testPageView() {
// Create a node to view.
diff --git a/core/modules/node/lib/Drupal/node/Tests/SummaryLengthTest.php b/core/modules/node/lib/Drupal/node/Tests/SummaryLengthTest.php
index 73fb431d8a0e..61b725a41107 100644
--- a/core/modules/node/lib/Drupal/node/Tests/SummaryLengthTest.php
+++ b/core/modules/node/lib/Drupal/node/Tests/SummaryLengthTest.php
@@ -7,6 +7,9 @@
namespace Drupal\node\Tests;
+/**
+ * Tests the summary length functionality.
+ */
class SummaryLengthTest extends NodeTestBase {
public static function getInfo() {
return array(
@@ -17,7 +20,7 @@ public static function getInfo() {
}
/**
- * Creates a node and then an anonymous and unpermissioned user attempt to edit the node.
+ * Tests the node summary length functionality.
*/
function testSummaryLength() {
// Create a node to view.
diff --git a/core/modules/node/node.admin.inc b/core/modules/node/node.admin.inc
index b35e839e7ac7..bca4dc20b6a2 100644
--- a/core/modules/node/node.admin.inc
+++ b/core/modules/node/node.admin.inc
@@ -1,12 +1,12 @@
<?php
-use Drupal\Core\Database\Query\SelectInterface;
-
/**
* @file
- * Content administration and module settings UI.
+ * Content administration and module settings user interface.
*/
+use Drupal\Core\Database\Query\SelectInterface;
+
/**
* Page callback: Form constructor for the permission rebuild confirmation form.
*
@@ -15,6 +15,7 @@
*
* @see node_configure_rebuild_confirm_submit()
* @see node_menu()
+ * @ingroup forms
*/
function node_configure_rebuild_confirm() {
return confirm_form(array(), t('Are you sure you want to rebuild the permissions on site content?'),
@@ -266,17 +267,15 @@ function node_filter_form_submit($form, &$form_state) {
/**
* Updates all nodes in the passed-in array with the passed-in field values.
*
- * IMPORTANT NOTE: This function is intended to work when called
- * from a form submission handler. Calling it outside of the form submission
- * process may not work correctly.
+ * IMPORTANT NOTE: This function is intended to work when called from a form
+ * submission handler. Calling it outside of the form submission process may not
+ * work correctly.
*
* @param array $nodes
* Array of node nids to update.
* @param array $updates
- * Array of key/value pairs with node field names and the value to update
- * that field to.
- *
- * @ingroup batch
+ * Array of key/value pairs with node field names and the value to update that
+ * field to.
*/
function node_mass_update($nodes, $updates) {
// We use batch processing to prevent timeout when updating a large number
@@ -402,6 +401,7 @@ function _node_mass_update_batch_finished($success, $results, $operations) {
* @see node_menu()
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
+ * @ingroup forms
*/
function node_admin_content($form, $form_state) {
if (isset($form_state['values']['operation']) && $form_state['values']['operation'] == 'delete') {
@@ -612,8 +612,8 @@ function node_admin_nodes() {
/**
* Form validation handler for node_admin_nodes().
*
- * Checks if any nodes have been selected to perform the chosen
- * 'Update option' on.
+ * Checks whether any nodes have been selected to perform the chosen 'Update
+ * option' on.
*
* @see node_admin_nodes()
* @see node_admin_nodes_submit()
@@ -674,6 +674,7 @@ function node_admin_nodes_submit($form, &$form_state) {
* @see node_filter_form()
* @see node_filter_form_submit()
* @see node_multiple_delete_confirm_submit()
+ * @ingroup forms
*/
function node_multiple_delete_confirm($form, &$form_state, $nodes) {
$form['nodes'] = array('#prefix' => '<ul>', '#suffix' => '</ul>', '#tree' => TRUE);
diff --git a/core/modules/node/node.api.php b/core/modules/node/node.api.php
index 113cc3d61cb7..c139952d690e 100644
--- a/core/modules/node/node.api.php
+++ b/core/modules/node/node.api.php
@@ -13,8 +13,8 @@
* Functions to define and modify content types.
*
* Each content type is maintained by a primary module, which is either
- * node.module (for content types created in the user interface) or the
- * module that implements hook_node_info() to define the content type.
+ * node.module (for content types created in the user interface) or the module
+ * that implements hook_node_info() to define the content type.
*
* During node operations (create, update, view, delete, etc.), there are
* several sets of hooks that get invoked to allow modules to modify the base
@@ -24,10 +24,10 @@
* function prefix. For example, poll.module defines the base for the Poll
* content type as "poll", so during creation of a poll node, hook_insert() is
* only invoked by calling poll_insert().
- * - All-module hooks: This set of hooks is invoked on all implementing
- * modules, to allow other modules to modify what the primary node module is
- * doing. For example, hook_node_insert() is invoked on all modules when
- * creating a poll node.
+ * - All-module hooks: This set of hooks is invoked on all implementing modules,
+ * to allow other modules to modify what the primary node module is doing. For
+ * example, hook_node_insert() is invoked on all modules when creating a poll
+ * node.
* - Field hooks: Hooks related to the fields attached to the node. These are
* invoked from the field operations functions described below, and can be
* either field-type-specific or all-module hooks.
@@ -58,7 +58,7 @@
* - hook_entity_update() (all)
* - hook_node_access_records() (all)
* - hook_node_access_records_alter() (all)
- * - Loading a node (calling node_load(), node_load_multiple(), entity_load()
+ * - Loading a node (calling node_load(), node_load_multiple(), entity_load(),
* or entity_load_multiple() with $entity_type of 'node'):
* - Node and revision information is read from database.
* - hook_load() (node-type-specific)
@@ -66,8 +66,7 @@
* - hook_entity_load() (all)
* - hook_node_load() (all)
* - Viewing a single node (calling node_view() - note that the input to
- * node_view() is a loaded node, so the Loading steps above are already
- * done):
+ * node_view() is a loaded node, so the Loading steps above are already done):
* - hook_view() (node-type-specific)
* - field_attach_prepare_view()
* - hook_entity_prepare_view() (all)
@@ -101,9 +100,8 @@
* - Revision information is deleted from database
* - hook_node_revision_delete() (all)
* - field_attach_delete_revision()
- * - Preparing a node for editing (calling node_form() - note that if it's
- * an existing node, it will already be loaded; see the Loading section
- * above):
+ * - Preparing a node for editing (calling node_form() - note that if it is an
+ * existing node, it will already be loaded; see the Loading section above):
* - hook_prepare() (node-type-specific)
* - hook_node_prepare() (all)
* - hook_form() (node-type-specific)
@@ -141,16 +139,16 @@
* associated with permission to view, edit, and delete individual nodes.
*
* The realms and grant IDs can be arbitrarily defined by your node access
- * module; it is common to use role IDs as grant IDs, but that is not
- * required. Your module could instead maintain its own list of users, where
- * each list has an ID. In that case, the return value of this hook would be
- * an array of the list IDs that this user is a member of.
+ * module; it is common to use role IDs as grant IDs, but that is not required.
+ * Your module could instead maintain its own list of users, where each list has
+ * an ID. In that case, the return value of this hook would be an array of the
+ * list IDs that this user is a member of.
*
- * A node access module may implement as many realms as necessary to
- * properly define the access privileges for the nodes. Note that the system
- * makes no distinction between published and unpublished nodes. It is the
- * module's responsibility to provide appropriate realms to limit access to
- * unpublished content.
+ * A node access module may implement as many realms as necessary to properly
+ * define the access privileges for the nodes. Note that the system makes no
+ * distinction between published and unpublished nodes. It is the module's
+ * responsibility to provide appropriate realms to limit access to unpublished
+ * content.
*
* Node access records are stored in the {node_access} table and define which
* grants are required to access a node. There is a special case for the view
@@ -184,7 +182,7 @@
* @param $account
* The user object whose grants are requested.
* @param $op
- * The node operation to be performed, such as "view", "update", or "delete".
+ * The node operation to be performed, such as 'view', 'update', or 'delete'.
*
* @return
* An array whose keys are "realms" of grants, and whose values are arrays of
@@ -262,6 +260,7 @@ function hook_node_grants($account, $op) {
* An array of grants as defined above.
*
* @see _node_access_write_grants()
+ * @see hook_node_access_records_alter()
* @ingroup node_access
*/
function hook_node_access_records(Drupal\node\Node $node) {
@@ -344,20 +343,19 @@ function hook_node_access_records_alter(&$grants, Drupal\node\Node $node) {
* Alter user access rules when trying to view, edit or delete a node.
*
* Node access modules establish rules for user access to content.
- * hook_node_grants() defines permissions for a user to view, edit or
- * delete nodes by building a $grants array that indicates the permissions
- * assigned to the user by each node access module. This hook is called to allow
- * modules to modify the $grants array by reference, so the interaction of
- * multiple node access modules can be altered or advanced business logic can be
- * applied.
+ * hook_node_grants() defines permissions for a user to view, edit or delete
+ * nodes by building a $grants array that indicates the permissions assigned to
+ * the user by each node access module. This hook is called to allow modules to
+ * modify the $grants array by reference, so the interaction of multiple node
+ * access modules can be altered or advanced business logic can be applied.
*
* The resulting grants are then checked against the records stored in the
* {node_access} table to determine if the operation may be completed.
*
* A module may deny all access to a user by setting $grants to an empty array.
*
- * Developers may use this hook to either add additional grants to a user
- * or to remove existing grants. These rules are typically based on either the
+ * Developers may use this hook to either add additional grants to a user or to
+ * remove existing grants. These rules are typically based on either the
* permissions assigned to a user role, or specific attributes of a user
* account.
*
@@ -404,10 +402,10 @@ function hook_node_grants_alter(&$grants, $account, $op) {
* @return
* An array of operations. Each operation is an associative array that may
* contain the following key-value pairs:
- * - 'label': Required. The label for the operation, displayed in the dropdown
+ * - label: (required) The label for the operation, displayed in the dropdown
* menu.
- * - 'callback': Required. The function to call for the operation.
- * - 'callback arguments': Optional. An array of additional arguments to pass
+ * - callback: (required) The function to call for the operation.
+ * - callback arguments: (optional) An array of additional arguments to pass
* to the callback function.
*/
function hook_node_operations() {
@@ -539,11 +537,10 @@ function hook_node_insert(Drupal\node\Node $node) {
/**
* Act on arbitrary nodes being loaded from the database.
*
- * This hook should be used to add information that is not in the node or
- * node revisions table, not to replace information that is in these tables
- * (which could interfere with the entity cache). For performance reasons,
- * information for all available nodes should be loaded in a single query where
- * possible.
+ * This hook should be used to add information that is not in the node or node
+ * revisions table, not to replace information that is in these tables (which
+ * could interfere with the entity cache). For performance reasons, information
+ * for all available nodes should be loaded in a single query where possible.
*
* This hook is invoked during node loading, which is handled by entity_load(),
* via classes NodeController and Drupal\Core\Entity\DatabaseStorageController.
@@ -583,15 +580,15 @@ function hook_node_load($nodes, $types) {
* Modules may implement this hook if they want to have a say in whether or not
* a given user has access to perform a given operation on a node.
*
- * The administrative account (user ID #1) always passes any access check,
- * so this hook is not called in that case. Users with the "bypass node access"
+ * The administrative account (user ID #1) always passes any access check, so
+ * this hook is not called in that case. Users with the "bypass node access"
* permission may always view and edit content through the administrative
* interface.
*
- * Note that not all modules will want to influence access on all
- * node types. If your module does not want to actively grant or
- * block access, return NODE_ACCESS_IGNORE or simply return nothing.
- * Blindly returning FALSE will break other node access modules.
+ * Note that not all modules will want to influence access on all node types. If
+ * your module does not want to actively grant or block access, return
+ * NODE_ACCESS_IGNORE or simply return nothing. Blindly returning FALSE will
+ * break other node access modules.
*
* Also note that this function isn't called for node listings (e.g., RSS feeds,
* the default home page at path 'node', a recent content block, etc.) See
@@ -665,8 +662,8 @@ function hook_node_prepare(Drupal\node\Node $node) {
/**
* Act on a node being displayed as a search result.
*
- * This hook is invoked from node_search_execute(), after node_load()
- * and node_view() have been called.
+ * This hook is invoked from node_search_execute(), after node_load() and
+ * node_view() have been called.
*
* @param Drupal\node\Node $node
* The node being displayed in a search result.
@@ -675,9 +672,9 @@ function hook_node_prepare(Drupal\node\Node $node) {
*
* @return array
* Extra information to be displayed with search result. This information
- * should be presented as an associative array. It will be concatenated
- * with the post information (last updated, author) in the default search
- * result theming.
+ * should be presented as an associative array. It will be concatenated with
+ * the post information (last updated, author) in the default search result
+ * theming.
*
* @see template_preprocess_search_result()
* @see search-result.tpl.php
@@ -740,8 +737,8 @@ function hook_node_update(Drupal\node\Node $node) {
/**
* Act on a node being indexed for searching.
*
- * This hook is invoked during search indexing, after node_load(), and after
- * the result of node_view() is added as $node->rendered to the node object.
+ * This hook is invoked during search indexing, after node_load(), and after the
+ * result of node_view() is added as $node->rendered to the node object.
*
* @param Drupal\node\Node $node
* The node being indexed.
@@ -766,16 +763,16 @@ function hook_node_update_index(Drupal\node\Node $node, $langcode) {
* Perform node validation before a node is created or updated.
*
* This hook is invoked from NodeFormController::validate(), after a user has
- * has finished editing the node and is previewing or submitting it. It is
- * invoked at the end of all the standard validation steps, and after the
- * type-specific hook_validate() is invoked.
+ * finished editing the node and is previewing or submitting it. It is invoked
+ * at the end of all the standard validation steps, and after the type-specific
+ * hook_validate() is invoked.
*
* To indicate a validation error, use form_set_error().
*
* Note: Changes made to the $node object within your hook implementation will
* have no effect. The preferred method to change a node's content is to use
- * hook_node_presave() instead. If it is really necessary to change
- * the node at the validate stage, you can use form_set_value().
+ * hook_node_presave() instead. If it is really necessary to change the node at
+ * the validate stage, you can use form_set_value().
*
* @param Drupal\node\Node $node
* The node being validated.
@@ -865,8 +862,8 @@ function hook_node_view(Drupal\node\Node $node, $view_mode, $langcode) {
* If the module wishes to act on the rendered HTML of the node rather than the
* structured content array, it may use this hook to add a #post_render
* callback. Alternatively, it could also implement hook_preprocess_HOOK() for
- * node.tpl.php. See drupal_render() and theme() documentation respectively
- * for details.
+ * node.tpl.php. See drupal_render() and theme() documentation respectively for
+ * details.
*
* @param $build
* A renderable array representing the node content.
@@ -893,8 +890,8 @@ function hook_node_view_alter(&$build, Drupal\node\Node $node) {
*
* This hook allows a module to define one or more of its own node types. For
* example, the forum module uses it to define a forum node-type named "Forum
- * topic." The name and attributes of each desired node type are specified in
- * an array returned by the hook.
+ * topic." The name and attributes of each desired node type are specified in an
+ * array returned by the hook.
*
* Only module-provided node types should be defined through this hook. User-
* provided (or 'custom') node types should be defined only in the 'node_type'
@@ -906,22 +903,22 @@ function hook_node_view_alter(&$build, Drupal\node\Node $node) {
* contains a sub-array for each node type, with the the machine name of a
* content type as the key. Each sub-array has up to 10 attributes.
* Possible attributes:
- * - "name": the human-readable name of the node type. Required.
- * - "base": the base string used to construct callbacks corresponding to
- * this node type.
- * (i.e. if base is defined as example_foo, then example_foo_insert will
- * be called when inserting a node of that type). This string is usually
- * the name of the module, but not always. Required.
- * - "description": a brief description of the node type. Required.
- * - "help": help information shown to the user when creating a node of
- * this type.. Optional (defaults to '').
- * - "has_title": boolean indicating whether or not this node type has a title
- * field. Optional (defaults to TRUE).
- * - "title_label": the label for the title field of this content type.
- * Optional (defaults to 'Title').
- * - "locked": boolean indicating whether the administrator can change the
- * machine name of this type. FALSE = changeable (not locked),
- * TRUE = unchangeable (locked). Optional (defaults to TRUE).
+ * - name: (required) The human-readable name of the node type.
+ * - base: (required) The base string used to construct callbacks
+ * corresponding to this node type (for example, if base is defined as
+ * example_foo, then example_foo_insert will be called when inserting a node
+ * of that type). This string is usually the name of the module, but not
+ * always.
+ * - description: (required) A brief description of the node type.
+ * - help: (optional) Help information shown to the user when creating a node
+ * of this type.
+ * - has_title: (optional) A Boolean indicating whether or not this node type
+ * has a title field.
+ * - title_label: (optional) The label for the title field of this content
+ * type.
+ * - locked: (optional) A Boolean indicating whether the administrator can
+ * change the machine name of this type. FALSE = changeable (not locked),
+ * TRUE = unchangeable (locked).
*
* The machine name of a node type should contain only letters, numbers, and
* underscores. Underscores will be converted into hyphens for the purpose of
@@ -970,20 +967,20 @@ function hook_node_info() {
* corresponding to the internal name of the ranking mechanism, such as
* 'recent', or 'comments'. The values should be arrays themselves, with the
* following keys available:
- * - "title": the human readable name of the ranking mechanism. Required.
- * - "join": part of a query string to join to any additional necessary
- * table. This is not necessary if the table required is already joined to
- * by the base query, such as for the {node} table. Other tables should use
- * the full table name as an alias to avoid naming collisions. Optional.
- * - "score": part of a query string to calculate the score for the ranking
- * mechanism based on values in the database. This does not need to be
- * wrapped in parentheses, as it will be done automatically; it also does
- * not need to take the weighted system into account, as it will be done
- * automatically. It does, however, need to calculate a decimal between
+ * - title: (required) The human readable name of the ranking mechanism.
+ * - join: (optional) The part of a query string to join to any additional
+ * necessary table. This is not necessary if the table required is already
+ * joined to by the base query, such as for the {node} table. Other tables
+ * should use the full table name as an alias to avoid naming collisions.
+ * - score: (required) The part of a query string to calculate the score for
+ * the ranking mechanism based on values in the database. This does not need
+ * to be wrapped in parentheses, as it will be done automatically; it also
+ * does not need to take the weighted system into account, as it will be
+ * done automatically. It does, however, need to calculate a decimal between
* 0 and 1; be careful not to cast the entire score to an integer by
- * inadvertently introducing a variable argument. Required.
- * - "arguments": if any arguments are required for the score, they can be
- * specified in an array here.
+ * inadvertently introducing a variable argument.
+ * - arguments: (optional) If any arguments are required for the score, they
+ * can be specified in an array here.
*
* @ingroup node_api_hooks
*/
@@ -1010,8 +1007,8 @@ function hook_ranking() {
/**
* Respond to node type creation.
*
- * This hook is invoked from node_type_save() after the node type is added
- * to the database.
+ * This hook is invoked from node_type_save() after the node type is added to
+ * the database.
*
* @param $info
* The node type object that is being created.
@@ -1023,8 +1020,8 @@ function hook_node_type_insert($info) {
/**
* Respond to node type updates.
*
- * This hook is invoked from node_type_save() after the node type is updated
- * in the database.
+ * This hook is invoked from node_type_save() after the node type is updated in
+ * the database.
*
* @param $info
* The node type object that is being updated.
@@ -1278,9 +1275,9 @@ function hook_validate(Drupal\node\Node $node, $form, &$form_state) {
* This hook is invoked only on the module that defines the node's content type
* (use hook_node_view() to act on all node views).
*
- * This hook is invoked during node viewing after the node is fully loaded,
- * so that the node type module can define a custom method for display, or
- * add to the default display.
+ * This hook is invoked during node viewing after the node is fully loaded, so
+ * that the node type module can define a custom method for display, or add to
+ * the default display.
*
* @param Drupal\node\Node $node
* The node to be displayed, as returned by node_load().
@@ -1288,16 +1285,15 @@ function hook_validate(Drupal\node\Node $node, $form, &$form_state) {
* View mode, e.g. 'full', 'teaser', ...
*
* @return
- * The passed $node parameter should be modified as necessary and
- * returned so it can be properly presented. Nodes are prepared for display
- * by assembling a structured array, formatted as in the Form API, in
- * $node->content. As with Form API arrays, the #weight property can be
- * used to control the relative positions of added elements. After this
- * hook is invoked, node_view() calls field_attach_view() to add field
- * views to $node->content, and then invokes hook_node_view() and
- * hook_node_view_alter(), so if you want to affect the final
- * view of the node, you might consider implementing one of these hooks
- * instead.
+ * The passed $node parameter should be modified as necessary and returned so
+ * it can be properly presented. Nodes are prepared for display by assembling
+ * a structured array, formatted as in the Form API, in $node->content. As
+ * with Form API arrays, the #weight property can be used to control the
+ * relative positions of added elements. After this hook is invoked,
+ * node_view() calls field_attach_view() to add field views to $node->content,
+ * and then invokes hook_node_view() and hook_node_view_alter(), so if you
+ * want to affect the final view of the node, you might consider implementing
+ * one of these hooks instead.
*
* @ingroup node_api_hooks
*/
diff --git a/core/modules/node/node.js b/core/modules/node/node.js
index e54a4d46de00..7a09356f3a4e 100644
--- a/core/modules/node/node.js
+++ b/core/modules/node/node.js
@@ -1,3 +1,8 @@
+/**
+ * @file
+ * Defines Javascript behaviors for the node module.
+ */
+
(function ($) {
"use strict";
diff --git a/core/modules/node/node.module b/core/modules/node/node.module
index 50395b12f4a5..541531228397 100644
--- a/core/modules/node/node.module
+++ b/core/modules/node/node.module
@@ -246,7 +246,7 @@ function node_field_display_node_alter(&$display, $context) {
* A node entity.
*
* @return array
- * An array with 'path' as the key and Node ID as its value.
+ * An array with 'path' as the key and the path to the node as its value.
*/
function node_uri(Node $node) {
return array(
@@ -483,6 +483,8 @@ function node_type_get_description($node_type) {
* node_type_save(), and obsolete ones are deleted via a call to
* node_type_delete(). See _node_types_build() for an explanation of the new
* and obsolete types.
+ *
+ * @see _node_types_build()
*/
function node_types_rebuild() {
_node_types_build(TRUE);
@@ -828,7 +830,8 @@ function node_type_cache_reset() {
*
* @param $info
* (optional) An object or array containing values to override the defaults.
- * See hook_node_info() for details on what the array elements mean.
+ * See hook_node_info() for details on what the array elements mean. Defaults
+ * to an empty array.
*
* @return
* A node type object, with missing values in $info set to their defaults.
@@ -952,8 +955,8 @@ function node_invoke($node, $hook, $a2 = NULL, $a3 = NULL, $a4 = NULL) {
* Loads node entities from the database.
*
* This function should be used whenever you need to load more than one node
- * from the database. Nodes are loaded into memory and will not require
- * database access if loaded again during the same page request.
+ * from the database. Nodes are loaded into memory and will not require database
+ * access if loaded again during the same page request.
*
* @param array $nids
* (optional) An array of entity IDs. If omitted, all entities are loaded.
@@ -1154,10 +1157,10 @@ function node_preprocess_block(&$variables) {
* variables.
*
* @param $variables
- * An array containing the following arguments:
- * - $node
- * - $view_mode
- * - $page
+ * An associative array containing:
+ * - elements: An array of elements to display in view mode.
+ * - node: The node object.
+ * - view_mode: View mode; e.g., 'full', 'teaser'...
*
* @see node.tpl.php
*/
@@ -1640,7 +1643,7 @@ function _node_revision_access(Node $node, $op = 'view', $account = NULL, $langc
* Access callback: Checks whether the user has permission to add a node.
*
* @return
- * TRUE if the user has permission, otherwise FALSE.
+ * TRUE if the user has add permission, otherwise FALSE.
*
* @see node_menu()
*/
@@ -1992,8 +1995,8 @@ function node_block_save($delta = '', $edit = array()) {
* (optional) The maximum number of nodes to find. Defaults to 10.
*
* @return
- * An array of node entities or an empty array if there are no recent
- * nodes visible to the current user.
+ * An array of node entities or an empty array if there are no recent nodes
+ * visible to the current user.
*/
function node_get_recent($number = 10) {
$query = db_select('node', 'n');
@@ -2340,8 +2343,8 @@ function node_feed($nids = FALSE, $channel = array()) {
* @param $view_mode
* (optional) View mode, e.g., 'full', 'teaser'... Defaults to 'full.'
* @param $langcode
- * (optional) A language code to use for rendering. Defaults to the global
- * content language of the current request.
+ * (optional) A language code to use for rendering. Defaults to NULL which is
+ * the global content language of the current request.
*
* @return
* An array as expected by drupal_render().
@@ -2689,8 +2692,8 @@ function node_form_system_themes_admin_form_submit($form, &$form_state) {
* @{
* The node access system determines who can do what to which nodes.
*
- * In determining access rights for a node, node_access() first checks
- * whether the user has the "bypass node access" permission. Such users have
+ * In determining access rights for a node, node_access() first checks whether
+ * the user has the "bypass node access" permission. Such users have
* unrestricted access to all nodes. user 1 will always pass this check.
*
* Next, all implementations of hook_node_access() will be called. Each
@@ -2705,8 +2708,8 @@ function node_form_system_themes_admin_form_submit($form, &$form_state) {
* is compared against the table. If any row contains the node ID in question
* (or 0, which stands for "all nodes"), one of the grant IDs returned, and a
* value of TRUE for the operation in question, then access is granted. Note
- * that this table is a list of grants; any matching row is sufficient to
- * grant access to the node.
+ * that this table is a list of grants; any matching row is sufficient to grant
+ * access to the node.
*
* In node listings (lists of nodes generated from a select query, such as the
* default home page at path 'node', an RSS feed, a recent content block, etc.),
@@ -2924,11 +2927,11 @@ function node_list_permissions($type) {
*
* By default, this will include all node types in the system. To exclude a
* specific node from getting permissions defined for it, set the
- * node_permissions_$type variable to 0. Core does not provide an interface
- * for doing so, however, contrib modules may exclude their own nodes in
+ * node_permissions_$type variable to 0. Core does not provide an interface for
+ * doing so. However, contrib modules may exclude their own nodes in
* hook_install(). Alternatively, contrib modules may configure all node types
- * at once, or decide to apply some other hook_node_access() implementation
- * to some or all node types.
+ * at once, or decide to apply some other hook_node_access() implementation to
+ * some or all node types.
*
* @return
* An array of node types managed by this module.
@@ -2947,12 +2950,12 @@ function node_permissions_get_configured_types() {
* Fetches an array of permission IDs granted to the given user ID.
*
* The implementation here provides only the universal "all" grant. A node
- * access module should implement hook_node_grants() to provide a grant
- * list for the user.
+ * access module should implement hook_node_grants() to provide a grant list for
+ * the user.
*
- * After the default grants have been loaded, we allow modules to alter
- * the grants array by reference. This hook allows for complex business
- * logic to be applied when integrating multiple node access modules.
+ * After the default grants have been loaded, we allow modules to alter the
+ * grants array by reference. This hook allows for complex business logic to be
+ * applied when integrating multiple node access modules.
*
* @param $op
* The operation that the user is trying to perform.
@@ -3047,11 +3050,10 @@ function node_access_view_all_nodes($account = NULL) {
/**
* Implements hook_query_TAG_alter().
*
- * This is the hook_query_alter() for queries tagged with 'node_access'.
- * It adds node access checks for the user account given by the 'account'
- * meta-data (or global $user if not provided), for an operation given by
- * the 'op' meta-data (or 'view' if not provided; other possible values are
- * 'update' and 'delete').
+ * This is the hook_query_alter() for queries tagged with 'node_access'. It adds
+ * node access checks for the user account given by the 'account' meta-data (or
+ * global $user if not provided), for an operation given by the 'op' meta-data
+ * (or 'view' if not provided; other possible values are 'update' and 'delete').
*/
function node_query_node_access_alter(AlterableInterface $query) {
global $user;
@@ -3167,15 +3169,14 @@ function node_access_acquire_grants(Node $node, $delete = TRUE) {
*
* If a realm is provided, it will only delete grants from that realm, but it
* will always delete a grant from the 'all' realm. Modules that utilize
- * node_access can use this function when doing mass updates due to widespread
+ * node_access() can use this function when doing mass updates due to widespread
* permission changes.
*
* Note: Don't call this function directly from a contributed module. Call
* node_access_acquire_grants() instead.
*
* @param Drupal\node\Node $node
- * The $node being written to. All that is necessary is that it contains a
- * nid.
+ * The node whose grants are being written.
* @param $grants
* A list of grants to write. Each grant is an array that must contain the
* following keys: realm, gid, grant_view, grant_update, grant_delete.
@@ -3189,6 +3190,8 @@ function node_access_acquire_grants(Node $node, $delete = TRUE) {
* (optional) If false, does not delete records. This is only for optimization
* purposes, and assumes the caller has already performed a mass delete of
* some form. Defaults to TRUE.
+ *
+ * @see node_access_acquire_grants()
*/
function _node_access_write_grants(Node $node, $grants, $realm = NULL, $delete = TRUE) {
if ($delete) {
@@ -3224,7 +3227,8 @@ function _node_access_write_grants(Node $node, $grants, $realm = NULL, $delete =
* This can be used as an alternative to direct node_access_rebuild calls,
* allowing administrators to decide when they want to perform the actual
* (possibly time consuming) rebuild.
- * When unsure the current user is an administrator, node_access_rebuild
+ *
+ * When unsure if the current user is an administrator, node_access_rebuild()
* should be used instead.
*
* @param $rebuild
@@ -3232,6 +3236,8 @@ function _node_access_write_grants(Node $node, $grants, $realm = NULL, $delete =
*
* @return
* The current value of the flag if no value was provided for $rebuild.
+ *
+ * @see node_access_rebuild()
*/
function node_access_needs_rebuild($rebuild = NULL) {
if (!isset($rebuild)) {
@@ -3319,11 +3325,11 @@ function node_access_rebuild($batch_mode = FALSE) {
}
/**
- * Batch operation for node_access_rebuild_batch.
+ * Performs batch operation for node_access_rebuild().
*
- * This is a multistep operation : we go through all nodes by packs of 20.
- * The batch processing engine interrupts processing and sends progress
- * feedback after 1 second execution time.
+ * This is a multistep operation: we go through all nodes by packs of 20. The
+ * batch processing engine interrupts processing and sends progress feedback
+ * after 1 second execution time.
*
* @param array $context
* An array of contextual key/value information for rebuild batch process.
@@ -3357,7 +3363,7 @@ function _node_access_rebuild_batch_operation(&$context) {
}
/**
- * Post-processing for node_access_rebuild_batch.
+ * Performs post-processing for node_access_rebuild().
*
* @param bool $success
* A boolean indicating whether the re-build process has completed.
@@ -3694,6 +3700,8 @@ function node_assign_owner_action_submit($form, $form_state) {
*
* @return array
* A form array.
+ *
+ * @see node_unpublish_by_keyword_action_submit()
*/
function node_unpublish_by_keyword_action_form($context) {
$form['keywords'] = array(
diff --git a/core/modules/node/node.pages.inc b/core/modules/node/node.pages.inc
index eef3d4268931..a71f5eb0ea17 100644
--- a/core/modules/node/node.pages.inc
+++ b/core/modules/node/node.pages.inc
@@ -62,9 +62,6 @@ function node_add_page() {
* An associative array containing:
* - content: An array of content types.
*
- * @return string
- * An HTML-formatted string.
- *
* @see node_add_page()
*
* @ingroup themeable
@@ -171,6 +168,7 @@ function node_preview(Node $node) {
* - node: The node entity which is being previewed.
*
* @see NodeFormController::preview()
+ * @see node_preview()
*
* @ingroup themeable
*/
@@ -211,6 +209,7 @@ function theme_node_preview($variables) {
* @return array
* A form array.
*
+ * @see node_delete_confirm_submit()
* @see node_menu()
*/
function node_delete_confirm($form, &$form_state, $node) {
@@ -324,6 +323,7 @@ function node_revision_overview($node) {
*
* @see node_menu()
* @see node_revision_revert_confirm_submit()
+ * @ingroup forms
*/
function node_revision_revert_confirm($form, $form_state, $node_revision) {
$form['#node_revision'] = $node_revision;
@@ -365,6 +365,7 @@ function node_revision_revert_confirm_submit($form, &$form_state) {
*
* @see node_menu()
* @see node_revision_delete_confirm_submit()
+ * @ingroup forms
*/
function node_revision_delete_confirm($form, $form_state, $node_revision) {
$form['#node_revision'] = $node_revision;
diff --git a/core/modules/node/tests/modules/node_access_test/node_access_test.module b/core/modules/node/tests/modules/node_access_test/node_access_test.module
index 33fe4d698e8d..4efee881a5f9 100644
--- a/core/modules/node/tests/modules/node_access_test/node_access_test.module
+++ b/core/modules/node/tests/modules/node_access_test/node_access_test.module
@@ -2,7 +2,9 @@
/**
* @file
- * Dummy module implementing node access related hooks to test API interaction
+ * A dummy module implementing node access related hooks for testing purposes.
+ *
+ * A dummy module implementing node access related hooks to test API interaction
* with the Node module. This module restricts view permission to those with
* a special 'node test view' permission.
*/
diff --git a/core/modules/node/tests/modules/node_test/node_test.module b/core/modules/node/tests/modules/node_test/node_test.module
index 49da0a081f6e..5e0a7ac21638 100644
--- a/core/modules/node/tests/modules/node_test/node_test.module
+++ b/core/modules/node/tests/modules/node_test/node_test.module
@@ -2,8 +2,10 @@
/**
* @file
- * Dummy module implementing node related hooks to test API interaction with
- * the Node module.
+ * A dummy module for testing node related hooks.
+ *
+ * This is a dummy module that implements node related hooks to test API
+ * interaction with the Node module.
*/
use Drupal\node\Plugin\Core\Entity\Node;
diff --git a/core/modules/node/tests/modules/node_test_exception/node_test_exception.module b/core/modules/node/tests/modules/node_test_exception/node_test_exception.module
index c5d11298fd35..359af1fbde91 100644
--- a/core/modules/node/tests/modules/node_test_exception/node_test_exception.module
+++ b/core/modules/node/tests/modules/node_test_exception/node_test_exception.module
@@ -2,8 +2,7 @@
/**
* @file
- * Dummy module implementing node related hooks to test API interaction with
- * the Node module.
+ * A module implementing node related hooks to test API interaction.
*/
use Drupal\node\Plugin\Core\Entity\Node;
--
GitLab