Problem/Motivation

Improve documention in \Drupal\Component\Utility\Unicode::truncate

Steps to reproduce

Proposed resolution

Add optional to the descriptions for $wordsafe, $add_ellipsis, and $min_wordsafe_length.
Refer to the latest patch which has already made the change.

Remaining tasks

Move the documentation changes in the latest patch to an MR.

User interface changes

API changes

Data model changes

Release notes snippet


Original report
I assume that we are now in code cleanup phase. I use PhpStorm to find possible bugs and problems in the Drupal 8 core. Normally I will not alter code flow. If I find problems in a file, which I will not fix, but find suspicious. I'll mention it in the text here.

For changes in the PHP Documentation I use this node as guide: http://drupal.org/node/1354

Checked: unicode.inc file.

CommentFileSizeAuthor
#1 drupal_core-code_cleanup_doc_cleanup_of_unicode.inc-1965508-1.patch8.16 KBro-no-lo

Issue fork drupal-1965508

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

ro-no-lo’s picture

ro-no-lo commented
Status: Active » Needs review
StatusFileSize
new drupal_core-code_cleanup_doc_cleanup_of_unicode.inc-1965508-1.patch8.16 KB

Patch added

enhdless’s picture

enhdless commented
Issue summary: View changes
Status: Needs review » Needs work

Patch fails to apply, it should be rerolled.

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.

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

Drupal 8 is end-of-life as of November 17, 2021. There will not be further changes made to Drupal 8. Bugfixes are now made to the 9.3.x and higher branches only. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.15 was released on June 1st, 2022 and is the final full bugfix release for the Drupal 9.3.x series. Drupal 9.3.x will not receive any further development aside from security fixes. Drupal 9 bug reports should be targeted for the 9.4.x-dev branch from now on, and new development or disruptive changes should be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.9 was released on December 7, 2022 and is the final full bugfix release for the Drupal 9.4.x series. Drupal 9.4.x will not receive any further development aside from security fixes. Drupal 9 bug reports should be targeted for the 9.5.x-dev branch from now on, and new development or disruptive changes should be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

quietone’s picture

quietone commented
Title: unicode.inc - Code Cleanup and Documentation additions » Improve doc block for Unicode::truncate()
Version: 9.5.x-dev » 11.x-dev
Issue summary: View changes
Issue tags: +Novice

This is still valid and is suitable for a first issue.

ro-no-lo’s picture

ro-no-lo commented

With the latest PHP 8.x I think we could avoid many of these phpDocs by just using the types inside the method signature.

jcorrao made their first commit to this issue’s fork.

jcorrao changed the visibility of the branch 1965508-improve-doc-block to hidden.

jcorrao opened merge request !7990

jcorrao’s picture

jcorrao
Primary language English
commented
Status: Needs work » Needs review

I have gone through and reviewed the patch file from #1 and ported the changes to the relevant counterpart in the 11.x codebase.

The type declarations in the PHPDoc patch were present in 11.x already, however they were missing the `(optional)` declaration as described in the linked PHP Documentation Standards page: http://drupal.org/node/1354

MR !7990 is published and ready for review.

smustgrave’s picture

smustgrave commented

So re-ran the tests but getting many failures and not sure why with just comments.

smustgrave’s picture

smustgrave commented
Status: Needs review » Needs work

Believe the issue has been fixed but just needs a rebase.

isa.bel made their first commit to this issue’s fork.

isa.bel opened merge request !11746

isa.bel closed merge request !11746

isa.bel’s picture

isa.bel
Primary language Portuguese, Brazil
Location Balneário Camboriú
commented
Status: Needs work » Needs review

I rebased the current branch using the latest version of core. Ready to be reviewed

smustgrave’s picture

smustgrave commented
Status: Needs review » Reviewed & tested by the community

Believe this is a net improvement.

xjm’s picture

xjm
she/her
Primary language English
commented
Status: Reviewed & tested by the community » Needs work

Added (optional) and the wrapping look correct. The only thing is that we have a pattern of describing the default behavior of optional parameters, e.g. "Defaults to FALSE" (and what that means for the behavior if the docblock doesn't already say). This is useful when the PHPDoc is being read outside the context of the codebase. Can we add that to these three parameters?

Thanks!

Saving credits.

nexusnovaz made their first commit to this issue’s fork.

nexusnovaz’s picture

nexusnovaz commented
Status: Needs work » Needs review

I've added some descriptions, i think this is good for review.

Thanks.

xjm’s picture

xjm
she/her
Primary language English
commented

I think those look great, thanks @nexusnovaz!

smustgrave’s picture

smustgrave commented
Status: Needs review » Reviewed & tested by the community

Believe feedback for this one has been addressed (sorry fell off my radar)

  • quietone committed 3c8dd1cd on 11.x 
    Issue #1965508 by jcorrao, smustgrave, ro-no-lo, isa.bel, xjm,...
quietone’s picture

quietone commented
Status: Reviewed & tested by the community » Fixed

I read the changes and they read well, the changes asked for by xjm have been made. They are no unanswered questions.

This is definitely an improvement. Thanks.
Committed 3c8dd1c and pushed to 11.x. Thanks!

Now that this issue is closed, please review the contribution record.

As a contributor, attribute any organization helped you, or if you volunteered your own time.

Maintainers, please credit people who helped resolve this issue.

quietone closed merge request !7990

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.