Update Doxygen for \Drupal\Component\DateTimePlus

+++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
@@ -132,6 +132,8 @@ public static function createFromDateTime(\DateTime $datetime, $settings = array
    * @return static
    *   A new \Drupal\Component\DateTimePlus object based on the parameters
    *   passed in.
+   * @throws \Exception
+   *   If array date values or value combination are not correct.
    */
   public static function createFromArray(array $date_parts, $timezone = NULL, $settings = array()) {

Total nit, but the convention is for a blank comment line between the sections, so there should be one above the @throws line.

Otherwise, fine with the wording; phrasing is consistent with other similar exceptions. This would be eligible under the allowed changes to go into 8.1.x as a patch release b/c it is an API documentation improvement. Should do a quick IS update to follow the template.

@ztl8702, normally, we try to post an interdiff when posting a new patch so we can see what has changed. No worries on this, though, since it is a simple patch.

I think it is worth to re-scope this issue to fix this issue for all the methods in DateTimePlus as there are quite a few methods in this class that throw exceptions

Edited IS to re-scope issue per #6 w/ the methods that PhpStorm complained about.

Thanks for the quick turnaround. Just a few small things, and I'll RTBC this.

1. +++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
   @@ -104,6 +104,10 @@ class DateTimePlus {
   +   * @return static
   +   *   A new \Drupal\Component\DateTimePlus object based on the parameters
   +   *   passed in.
       */
   

   General convention in core is to not fully qualify the class in these. I think it can simply be "A new DateTimePlus object." (This is somewhat obvious from the static constructors, but this pattern is used a lot in core.)

2. +++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
   @@ -155,6 +162,13 @@ public static function createFromArray(array $date_parts, $timezone = NULL, $set
   +   * @return static
   +   *   A new \Drupal\Component\DateTimePlus object based on the parameters
   +   *   passed in.
   +   *
   

   Same as above.

3. +++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
   @@ -187,6 +201,14 @@ public static function createFromTimestamp($timestamp, $timezone = NULL, $settin
   +   * @return static
   +   *   A new \Drupal\Component\DateTimePlus object based on the parameters
   +   *   passed in.
   +   *
   

   Same as above.

4. +++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
   @@ -324,6 +346,8 @@ public function __clone() {
   +   *
   +   * @return mixed
       */
   

   For future reviewers, I think the comment on the method when you read this in context explains this fully and more details on the return value isn't needed.

5. +++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
   @@ -338,6 +362,9 @@ protected function prepareTime($time) {
   +   *
   +   * @return \DateTimeZone
   +   *   A \DateTimeZone object based on the timezone passed in.
   

   Same as above.

6. +++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
   @@ -370,6 +397,8 @@ protected function prepareTimezone($timezone) {
   +   *
   +   * @return string
   

   As above, I'm fine w/o additional info here.

@mpdonadio thanks for your detailed instructions.

Thanks, I think this looks perfect. But, I need to read it applied before I RTBC it, which I can't do until tonight.

OK, patch looks good. In looking at this in context, let's do this right and also add

- @return for hasErrors
- @return for getErrors

so they at least typehint properly.

The docs in this class aren't up to our current quality, but I think I want to stop the scope of the issue here. The protected properties need types, and some of the comments are wrong, but we can clean that up later.

added @return boolean and @return string to hasErrors and getErrors

I am new here and want to learn.
Please correct if I anything wrong

#16, thanks for the patch. We normally try to post an interdiff so we can easily see what has changed patch-to-patch. I attached one for your changes.

+++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
@@ -408,6 +432,8 @@ public function checkErrors() {
@@ -417,6 +443,8 @@ public function hasErrors() {

@@ -417,6 +443,8 @@ public function hasErrors() {
    * Gets error messages.
    *
    * Public function to return the error messages.
+   *
+   * @return string
    */

This is an array.

Sorry @mpdonadio, for some reason I want not able to upload the interdiff.
Made changes again uploading interdiff

This class still has issues, but I am happy with the improvements that this patch provides. Further doc updates are premature before we look at better look at whether there are refactoring opportunities.

+++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
@@ -329,6 +347,8 @@ public function __clone() {
+   *
+   * @return mixed

@@ -343,6 +363,8 @@ protected function prepareTime($time) {
+   *
+   * @return \DateTimeZone

@@ -375,6 +397,8 @@ protected function prepareTimezone($timezone) {
+   *
+   * @return string

@@ -408,6 +432,8 @@ public function checkErrors() {
+   *
+   * @return boolean

@@ -417,6 +443,8 @@ public function hasErrors() {
+   *
+   * @return array

If we are going to add these @return's in this patch then let's at least not docs which don't conform to the standards. These all need a description.

Thanks. I think we need a few tweaks before this is ready. DREditor is being weird. I hope these make sense.

1. +++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
   @@ -324,6 +342,10 @@ public function __clone() {
   +   * @return mixed
   +   *   An input value, which could be a timestamp, a string, or an array of date
   +   *   parts.
       */
   

   For the return value for prepareTime(), how about 'The massaged time.'

2. +++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
   @@ -338,6 +360,9 @@ protected function prepareTime($time) {
   +   * @return \DateTimeZone
   +   *   A DateTimeZone object.
       */
   

   For prepareTimezone(), how about 'The massaged time zone.'

3. +++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
   @@ -370,6 +395,9 @@ protected function prepareTimezone($timezone) {
   +   * @return string
   +   *   A PHP format string.
       */
   

   For prepareFormat(), how about 'The massaged PHP format string.'

These better match the comments where they are used.

Read this in place, and it looks good. Think all feedback has been addressed. This is eligible for 8.1.x per the policy under "API documentation improvements."

Committed 864055b and pushed to 8.1.x and 8.2.x. Thanks!