Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8140211

Example in the Documentation is wrong for java.time.ZonedDateTime.minusHours

    Details

    • Type: Bug
    • Status: Resolved
    • Priority: P4
    • Resolution: Fixed
    • Affects Version/s: 8u60, 9
    • Fix Version/s: 9
    • Component/s: core-libs
    • Labels:
    • Subcomponent:
    • Resolved In Build:
      b106

      Description

      A DESCRIPTION OF THE REQUEST :
      The java doc for
      public ZonedDateTime minusHours(long hours)
      ...
         * For example, consider a time-zone where the spring DST cutover means that the
           * local times 01:00 to 01:59 occur twice changing from offset +02:00 to +01:00.
           * <ul>
           * <li>Subtracting one hour from 02:30+01:00 will result in 01:30+02:00
           * <li>Subtracting one hour from 01:30+01:00 will result in 01:30+02:00
           * <li>Subtracting one hour from 01:30+02:00 will result in 00:30+01:00
           * <li>Subtracting three hours from 02:30+01:00 will result in 00:30+02:00
      ...
      the first example is wrong. It should read
           * <li>Subtracting one hour from 02:30+01:00 will result in 01:30+01:00

      JUSTIFICATION :
      Wrong documentation


        Activity

        Hide
        psonal Pallavi Sonal added a comment - - edited
        http://docs.oracle.com/javase/8/docs/api/ -> java.time -> ZonedDateTime -> minusHours
        http://download.java.net/jdk9/docs/api/index.html -> java.time -> ZonedDateTime -> minusHours

        The example describing the outputs of minusHours when considering a DST , when clock moves backwards from 02:00 to 01:00 , has wrong output in the first and third example:
        "Subtracting one hour from 02:30+01:00 will result in 01:30+02:00 " - This should be - "Subtracting one hour from 02:30+01:00 will result in 01:30+01:00"
        "Subtracting one hour from 01:30+02:00 will result in 00:30+01:00" - This should be -"Subtracting one hour from 01:30+02:00 will result in 00:30+02:00 "

        The outputs generated by the API are correct though. Attached Testcase uses TimeZone Europe/Paris +02:00 , on date 25Oct 2015 when clock moves back from 03:00 to 02:00. All the outputs are as expected.

        Moving across to dev-team for action.
        Show
        psonal Pallavi Sonal added a comment - - edited http://docs.oracle.com/javase/8/docs/api/ -> java.time -> ZonedDateTime -> minusHours http://download.java.net/jdk9/docs/api/index.html -> java.time -> ZonedDateTime -> minusHours The example describing the outputs of minusHours when considering a DST , when clock moves backwards from 02:00 to 01:00 , has wrong output in the first and third example: "Subtracting one hour from 02:30+01:00 will result in 01:30+02:00 " - This should be - "Subtracting one hour from 02:30+01:00 will result in 01:30+01:00" "Subtracting one hour from 01:30+02:00 will result in 00:30+01:00" - This should be -"Subtracting one hour from 01:30+02:00 will result in 00:30+02:00 " The outputs generated by the API are correct though. Attached Testcase uses TimeZone Europe/Paris +02:00 , on date 25Oct 2015 when clock moves back from 03:00 to 02:00. All the outputs are as expected. Moving across to dev-team for action.
        Hide
        scolebourne Stephen Colebourne added a comment -
        Sadly, the documentation for both minusHours(long) and 'plusHours(long)' is confused.

        Both refer to the "spring DST cutover" when they are obviously referring to the "autumn DST cutover" instead. A suitable time-zone for testing the example would be Europe/Paris, but it goes from +02:00 to +01:00 one hour later (ie. 02:00 to 02:59 is repeated). Because the first sentence is confused, it is hard to make sense of, or replicate, the second part.

        Thus the docs should be:

        "
        For example, consider a time-zone, such as 'Europe/Paris', where the autumn daylight savings cutover means that the local times 02:00 to 02:59 occur twice changing from offset +02:00 in summer to +01:00 in winter."
        <ul>
         <li>Subtracting one hour from 03:30+01:00 will result in 02:30+01:00 (both in winter time)
         <li>Subtracting one hour from 02:30+01:00 will result in 02:30+02:00 (moving from winter to summer time)
         <li>Subtracting one hour from 02:30+02:00 will result in 01:30+02:00 (both in summer time)
         <li>Subtracting three hours from 03:30+01:00 will result in 01:30+02:00 (moving from winter to summer time)
        </ul>
        "

        The plusHours(long) docs should be changed in the same way.
        Show
        scolebourne Stephen Colebourne added a comment - Sadly, the documentation for both minusHours(long) and 'plusHours(long)' is confused. Both refer to the "spring DST cutover" when they are obviously referring to the "autumn DST cutover" instead. A suitable time-zone for testing the example would be Europe/Paris, but it goes from +02:00 to +01:00 one hour later (ie. 02:00 to 02:59 is repeated). Because the first sentence is confused, it is hard to make sense of, or replicate, the second part. Thus the docs should be: " For example, consider a time-zone, such as 'Europe/Paris', where the autumn daylight savings cutover means that the local times 02:00 to 02:59 occur twice changing from offset +02:00 in summer to +01:00 in winter." <ul>  <li>Subtracting one hour from 03:30+01:00 will result in 02:30+01:00 (both in winter time)  <li>Subtracting one hour from 02:30+01:00 will result in 02:30+02:00 (moving from winter to summer time)  <li>Subtracting one hour from 02:30+02:00 will result in 01:30+02:00 (both in summer time)  <li>Subtracting three hours from 03:30+01:00 will result in 01:30+02:00 (moving from winter to summer time) </ul> " The plusHours(long) docs should be changed in the same way.
        Hide
        hgupdate HG Updates added a comment -
        URL: http://hg.openjdk.java.net/jdk9/dev/jdk/rev/c3d07e37041d
        User: rriggs
        Date: 2016-02-11 16:43:50 +0000
        Show
        hgupdate HG Updates added a comment - URL: http://hg.openjdk.java.net/jdk9/dev/jdk/rev/c3d07e37041d User: rriggs Date: 2016-02-11 16:43:50 +0000
        Hide
        hgupdate HG Updates added a comment -
        URL: http://hg.openjdk.java.net/jdk9/jdk9/jdk/rev/c3d07e37041d
        User: lana
        Date: 2016-02-17 20:42:45 +0000
        Show
        hgupdate HG Updates added a comment - URL: http://hg.openjdk.java.net/jdk9/jdk9/jdk/rev/c3d07e37041d User: lana Date: 2016-02-17 20:42:45 +0000

          People

          • Assignee:
            rriggs Roger Riggs
            Reporter:
            webbuggrp Webbug Group
          • Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: