This issue is part of #1861442: [meta] Review of Drupal\Component\GetText files that aims to clean up the Gettext component.

Problem/Motivation

The code of the Gettext component is not consistent with the current Drupal coding and documentation standards.

Proposed resolution

  • Fix the docblock comments in the Gettext component files.
CommentFileSizeAuthor
#24 2935189-nr-bot.txt168 bytesneeds-review-queue-bot
#14 drupal-gettext-docblock-2935189-13.patch18.57 KBSutharsan
#14 interdiff-2935189-12-13.txt1.01 KBSutharsan
#13 drupal-gettext-docblock-2935189-12.patch18.29 KBSutharsan
#10 drupal-gettext-docblock-2935189-10.patch18.87 KBSutharsan
#10 interdiff-2935189-7-10.txt860 bytesSutharsan
#7 drupal-gettext-docblock-2935189-5.patch18.87 KBSutharsan
#7 interdiff-2935189-2-5.txt1.38 KBSutharsan
#3 drupal-gettext-docblock-2935189-3.patch18.83 KBSutharsan
#2 drupal-gettext-docblock-2935189-2.patch10.49 KBSutharsan
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Sutharsan created an issue. See original summary.

Sutharsan’s picture

Sutharsan CreditAttribution: Sutharsan at LimoenGroen commented
Assigned: Sutharsan » Unassigned
Issue summary: View changes
Status: Active » Needs review
FileSize
drupal-gettext-docblock-2935189-2.patch10.49 KB
Sutharsan’s picture

Sutharsan CreditAttribution: Sutharsan at LimoenGroen commented
FileSize
drupal-gettext-docblock-2935189-3.patch18.83 KB

Wrong patch, review this one.

cilefen’s picture

cilefen CreditAttribution: cilefen at Institute for Advanced Study commented
Title: Complete dockblock comments in Gettext component. » Complete docblock comments in Gettext component.

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

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now 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.

mikispeed’s picture

mikispeed CreditAttribution: mikispeed at Develomon commented
Status: Needs review » Needs work 
  1. +++ b/core/lib/Drupal/Component/Gettext/PoItem.php
@@ -29,7 +29,7 @@ class PoItem {
+   * @see self::_plural

@@ -51,7 +51,8 @@ class PoItem {
+   * @see self::_plural

    Well, this is changed in #2935190 and will need work after that one is merged. 

  2. +++ b/core/lib/Drupal/Component/Gettext/PoWriterInterface.php
@@ -21,8 +21,8 @@ public function writeItem(PoItem $item);
+   *   Amount of items to read from $reader to write. Defaults to -1, all items

    This is not clear. I would rephrase to be clear what is default value and what is behavior if -1. For example:

    Amount of items to read from $reader to write. Defaults to -1. If -1, all items are read from $reader.
Sutharsan’s picture

Sutharsan CreditAttribution: Sutharsan at LimoenGroen commented
Status: Needs work » Needs review
FileSize
interdiff-2935189-2-5.txt1.38 KB
drupal-gettext-docblock-2935189-5.patch18.87 KB

Well, this is changed in #2935190, ...

Agree that will require a re-roll, but I did this for separation of issues.

Comment 2 addressed.
One missing @param type hint found.

mikispeed’s picture

mikispeed CreditAttribution: mikispeed at Develomon commented
Status: Needs review » Reviewed & tested by the community

This now looks good, marking as Reviewed.

alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
CreditAttribution: alexpott at Acro Commerce commented
Status: Reviewed & tested by the community » Needs work 
  1. +++ b/core/lib/Drupal/Component/Gettext/PoStreamInterface.php
@@ -3,36 +3,48 @@
+   * @throws \Exception
...
+   * @throws \Exception
...
+   * @throws \Exception

    We should open a followup as I strongly suspect that the exceptions thrown in \Drupal\Component\Gettext\PoStreamWriter::close(), ::write() and ::getURI() don't actually work because they are not namespaced properly. They all need to be prefixed with a \ 

  2. +++ b/core/lib/Drupal/Component/Gettext/PoStreamReader.php
@@ -237,7 +227,7 @@ private function readHeader() {
+   * @return false|null

    This should be
    * @return null|void
    sine the returns are just return;

Sutharsan’s picture

Sutharsan CreditAttribution: Sutharsan at LimoenGroen commented
Status: Needs work » Needs review
FileSize
interdiff-2935189-7-10.txt860 bytes
drupal-gettext-docblock-2935189-10.patch18.87 KB

We should open a followup ...

See #2935193: Fix broken exceptions in Gettext component

This should be @return null|void sine the returns are just return;

I guess you mean @return false|void. Although void as return type was been introduced in PHP 7.1, it makes sense to use it in documentation to express that no value is returned intentionally. PHP 7.0 and below implicitly uses NULL. See https://wiki.php.net/rfc/void_return_type for info.

borisson_’s picture

borisson_
Primary language Dutch
Location Mechelen, 🇧🇪
CreditAttribution: borisson_ as a volunteer commented 
+++ b/core/lib/Drupal/Component/Gettext/PoStreamReader.php
@@ -237,7 +227,7 @@ private function readHeader() {
+   * @return false|void
    *   FALSE if an error was logged, NULL otherwise. The errors are considered

instead of NULL otherwise, this could say nothing otherwise? We changed the @return, so we should probably update this as well?

Not 100% sure that is something that we should do though. Otherwise this looks solid!

borisson_’s picture

borisson_
Primary language Dutch
Location Mechelen, 🇧🇪
CreditAttribution: borisson_ as a volunteer commented
Status: Needs review » Needs work

Setting to needs work based on #11.

Sutharsan’s picture

Sutharsan CreditAttribution: Sutharsan at LimoenGroen commented
FileSize
drupal-gettext-docblock-2935189-12.patch18.29 KB

A re-roll to start with...

Sutharsan’s picture

Sutharsan CreditAttribution: Sutharsan at LimoenGroen commented
Status: Needs work » Needs review
FileSize
interdiff-2935189-12-13.txt1.01 KB
drupal-gettext-docblock-2935189-13.patch18.57 KB

Comment #11 addressed.

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

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now 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.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.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.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). 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.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now 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: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

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

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.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.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.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.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now 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.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now 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.

needs-review-queue-bot’s picture

needs-review-queue-bot CreditAttribution: needs-review-queue-bot as a volunteer commented
Status: Needs review » Needs work
FileSize
2935189-nr-bot.txt168 bytes

The Needs Review Queue Bot tested this issue. It either no longer applies to Drupal core, or fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

Apart from a re-roll or rebase, this issue may need more work to address feedback in the issue or MR comments. To progress an issue, incorporate this feedback as part of the process of updating the issue. This helps other contributors to know what is outstanding.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.