Standardize getter docblocks in node module

Rerolled and extended.

Looks good.

Thanks @anavarre and @bojanz! The reformatting of the one-line summaries is all fine, but if we're also adding the return value documentation as part of the scope, can we do a little more work to make it more useful? Specifically:

1. +++ b/core/modules/node/src/NodePermissions.php
   @@ -20,9 +20,10 @@ class NodePermissions {
       * @return array
   +   *   The content permissions.
   
   @@ -34,9 +35,10 @@ public function contentPermissions() {
       * @return array
   +   *   The node type permissions.
   

   So normally, we would document the structure of an array for multidimensional array formats -- otherwise it's just redundant and not really helpful. I guess we could just reference PermissionHandlerInterface?

2. +++ b/core/modules/node/src/Plugin/views/wizard/Node.php
   @@ -48,6 +48,7 @@ class Node extends WizardPluginBase {
       * @return array
   +   *   The available sorts.
   

   Same here; can we make this a little more useful if we are adding this documentation? What is the data type of the array children?

3. +++ b/core/modules/node/src/Tests/NodeCreationTest.php
   @@ -190,9 +190,10 @@ function testNodeAddWithoutContentTypes () {
       * @return array
   +   *   The log records with the rollback exception message.
   
   @@ -209,9 +210,10 @@ protected static function getWatchdogIdsForTestExceptionRollback() {
       * @return array
   +   *   The log records with the explicit rollback failed exception message.
   

   Are these actually \Drupal\Core\Database\StatementInterface[] rather than just array?

4. +++ b/core/modules/node/src/Tests/NodeTestBase.php
   @@ -103,6 +103,7 @@ function assertNodeCreateAccess($bundle, $result, AccountInterface $account, $la
       * @return string
   +   *   Assert message for checking node access.
   

   This description also isn't really clear; could we improve it?

1. +++ b/core/modules/node/src/NodePermissions.php
   @@ -39,6 +39,7 @@ public function contentPermissions() {
   +   *   @see \Drupal\user\PermissionHandlerInterface::getPermissions().
   

   Please remove the trailing dot.

2. +++ b/core/modules/node/src/Plugin/views/wizard/Node.php
   @@ -48,7 +48,8 @@ class Node extends WizardPluginBase {
   +   *   corresponding values are human readble labels.
   

   s/readble/readable

3. +++ b/core/modules/node/src/Tests/NodeCreationTest.php
   @@ -190,10 +190,11 @@ function testNodeAddWithoutContentTypes () {
   +   * Gets the wids of the log records with the rollback exception message.
   

   I wonder if we should replace 'wids' by something more explicit (after all this is documentation) like 'Watchdog IDs'?

4. +++ b/core/modules/node/src/Tests/NodeCreationTest.php
   @@ -190,10 +190,11 @@ function testNodeAddWithoutContentTypes () {
   +   *   Array containing the wid of the log recoards with the the rollback
   

   s/recoards/records

Thanks! - I think all of @xjm's points have been addressed. Tentatively marking this back to RTBC.

Nice, thanks! That works. Two other minor cleanups (which I almost could have fixed on commit) but also one more substantive question.

1. +++ b/core/modules/node/src/Tests/NodeCreationTest.php
   @@ -190,9 +190,11 @@ function testNodeAddWithoutContentTypes () {
   -   * Returns log records with the rollback exception message.
   +   * Gets the watchdog IDs of the records with the rollback exception message.
       *
   -   * @return array
   +   * @return int[]
   +   *   Array containing the ID of the log records with the the rollback
   +   *   exception message.
       */
      protected static function getWatchdogIdsForTestExceptionRollback() {
        // PostgreSQL doesn't support bytea LIKE queries, so we need to unserialize
   @@ -209,9 +211,10 @@ protected static function getWatchdogIdsForTestExceptionRollback() {
   
   @@ -209,9 +211,10 @@ protected static function getWatchdogIdsForTestExceptionRollback() {
      }
    
      /**
   -   * Returns log records with the explicit rollback failed exception message.
   +   * Gets the log records with the explicit rollback failed exception message.
       *
       * @return array
   +   *   The log records with the explicit rollback failed exception message.
       */
      protected static function getWatchdogIdsForFailedExplicitRollback() {
   

   Shouldn't these two docblocks be similar? Also I don't quite understand the difference between them now (reading it).

2. +++ b/core/modules/node/src/Tests/NodeTestBase.php
   @@ -92,7 +92,7 @@ function assertNodeCreateAccess($bundle, $result, AccountInterface $account, $la
   -   * Constructs an assert message for checking node access.
   +   * Constructs an assert message to display which node access was done.
   

   Maybe "which node access was tested"?

3. +++ b/core/modules/node/src/Tests/NodeTestBase.php
   @@ -103,6 +103,8 @@ function assertNodeCreateAccess($bundle, $result, AccountInterface $account, $la
   +   *   Assert message string which contains information in plain english about
   +   *   which node access permission test was performed.
   

   Minor: "english" should be capitalized.

@jaredsmith said he could take a look at this quickly.

I fixed up the issues identified by @xjm in comment 9. I also fixed a couple of other minor grammar issues along the way.

I'm setting this back to RTBC, as the changes are very minor. (If you disagree, feel free to set it back to "Needs Review".)

Thanks, @jaredsmith - Fixing a super minor remaining nit.

Excellent, thanks @jaredsmith, @anavarre, and @googletorp for the quick fixes.

+++ b/core/modules/node/src/Tests/NodeCreationTest.php
@@ -190,9 +190,11 @@ function testNodeAddWithoutContentTypes () {
-   * Returns log records with the rollback exception message.
+   * Gets the watchdog IDs of the records with the rollback exception message.
    *
-   * @return array
+   * @return int[]
+   *   Array containing the IDs of the log records with the rollback exception
+   *   message.
    */
   protected static function getWatchdogIdsForTestExceptionRollback() {
     // PostgreSQL doesn't support bytea LIKE queries, so we need to unserialize
@@ -209,9 +211,11 @@ protected static function getWatchdogIdsForTestExceptionRollback() {

   /**
-   * Returns log records with the explicit rollback failed exception message.
+   * Gets the log records with the explicit rollback failed exception message.
    *
-   * @return array
+   * @return \Drupal\Core\Database\StatementInterface
+   *   A prepared statement object (already executed), which contains the log
+   *   records with the explicit rollback failed exception message.
    */
   protected static function getWatchdogIdsForFailedExplicitRollback() {

Hah, so the latter method is just misleadingly named (I confirmed these updated docs are correct after reading the test). The method names are not in scope, though, and the improved documentation from this patch will offset that in any case.

This issue only changes documentation, so per https://www.drupal.org/core/beta-changes, this can be completed any time during the Drupal 8 beta phase. Committed and pushed to 8.0.x. Thanks!