According to Drupal's documentation standards, variable declarations (@var), parameters (@param) and return (@return) values for Boolean values should use 'bool' instead of some variation of 'boolean'. The intent of this issue is to start to correct existing documentation violations to conform with this standard.

CommentFileSizeAuthor
#2 1860690-2-boolean.patch44.94 KBlars toomre

Comments

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Postponed

You should be able to use some search-and-replace script to do this change, and if you can limit your patch to only this change, it should be easy to review/commit.

However, this type of cleanup should probably wait a while. There is a lot of patch activity right now, and cleanup patches interfere with other people trying to get real code and documentation improvements completed.

lars toomre’s picture

lars toomre commented
Status: Postponed » Needs review
StatusFileSize
new 1860690-2-boolean.patch44.94 KB

Thanks for your initial thoughts @jhodgdon. I had been working on an initial patch before your post in #1.

Attached is an initial (and untested hand-created) patch that starts to address this issue. While I appreciate that a core committer can postpone this issue at any time, I would hope that this initial patch can be considered since it touches numerous files that have been in core for some time.

Also, a simple search-and-replace script would not identify instances where '@var boolean' is incorrect given that the class property is assigned a string as a default value. Carefully reading through the docblocks results in better accuracy, at least in my opinion.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs review » Postponed

Sorry, patches that touch a huge number of files are postponed for now.

lars toomre’s picture

lars toomre commented

Please define what "A huge number of files" are. It will help to focus on what can be committed on a somewhat timely manner.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Widespread cleanups are postponed until the cleanup phase of this release. This seems to be a widespread cleanup, so I've postponed it. When I looked at the patch, it had a very long list of files in it. I don't have an exact number for you, and I'm sorry if you are finding that frustrating, but really we're trying to concentrate on features and APIs and actual code, not cleaning up style problems at this time.

lars toomre’s picture

lars toomre commented

Given a lack of direction, I am going to assume that a patch that does not touch more than ten files is not considered "huge".

I also appreciate that the main focus of D8 is on "features and APIs and actual code". However, when reading through core files/patches, there should be some mechanism to fix issues that one might identify. Or are incremental documentation fix patches inappropriate until (some unidentified time)?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

If there is an actual documentation bug, those can be fixed as we go, at any time. But we do not want to do "cleanup" issues that just address standards adherence rather than clarity and accuracy right now. Thanks!

mgifford’s picture

mgifford
he/him
Primary language English
commented
Issue summary: View changes
Status: Postponed » Active

Now that Beta1's out is this a good time to address this?

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.6 was released on February 1, 2017 and is the final full bugfix release for the Drupal 8.2.x series. Drupal 8.2.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.3.0 on April 5, 2017. (Drupal 8.3.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.3.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.4 was released on January 3, 2018 and is the final full bugfix release for the Drupal 8.4.x series. Drupal 8.4.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.5.0 on March 7, 2018. (Drupal 8.5.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.5.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.6 was released on August 1, 2018 and is the final bugfix release for the Drupal 8.5.x series. Drupal 8.5.x will not receive any further development aside from security fixes. Sites should prepare to update to 8.6.0 on September 5, 2018. (Drupal 8.6.0-rc1 is available for testing.)

Bug reports should be targeted against the 8.6.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.8.x-dev

Drupal 8.6.x will not receive any further development aside from security fixes. Bug reports should be targeted against the 8.8.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.9.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.7 was released on June 3, 2020 and is the final full bugfix release for the Drupal 8.8.x series. Drupal 8.8.x will not receive any further development aside from security fixes. Sites should prepare to update to Drupal 8.9.0 or Drupal 9.0.0 for ongoing support.

Bug reports should be targeted against the 8.9.x-dev branch from now on, and new development or disruptive changes should be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

quietone’s picture

quietone commented
Status: Active » Closed (outdated)
Issue tags: +Bug Smash Initiative

There have been a lot of fixes related to coding standards and I suspect this is now outdated. And not surprisingly the latest patch no longer applies.

I found these two issue which address the use of boolean in @var, @return and @param.

So, I think that has been fixed and it is safe to close this as outdated.

If you disagree, please reopen.