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

Map default methods in JDK 8 have poor Javadoc

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Open
    • Priority: P4
    • Resolution: Unresolved
    • Affects Version/s: 8
    • Fix Version/s: tbd
    • Component/s: core-libs
    • Labels:
      None

      Description

      The Javadoc for the new default methods in Map are poor. A Javadoc description should start with the positive, not the negative. I had to read the code to figure out what they are supposed to do. Here are the four poor Javadocs and some proposed enhancements:


      merge()
      "If the specified key is not already associated with ..."
      should be:
      "Updates the value for an existing key merging the existing value with the specified value."
      "<p>"
      "....more detailed user-level explanation..."
      "<p>"
      "....now the more spec/edge case part..."
      ("if" is a terrible way to start the docs. Say what it does!)


      computeIfAbsent()
      "If the specified key is not already associated with a value (or is mapped..."
      should be:
      "Associates the key with a value computed on demand if the key is not currently present."
      "<p>"
      "....more detailed user-level explanation..."
      "<p>"
      "....now the more spec/edge case part..."


      computeIfPresent()
      "If the value for the specified key is present and non-null,"
      should be
      "Updates the value for an existing key."
      "<p>"
      "....more detailed user-level explanation..."
      "<p>"
      "....now the more spec/edge case part..."


      compute()
      "Attempts to compute a mapping for the specified key..."
      should be
      "Updates the value for a key, adding a new mapping if necessary."
      "<p>"
      "....more detailed user-level explanation..."
      "<p>"
      "....now the more spec/edge case part..."
      (attempts is negative, not positive)


      Similar problems seem to exist for "putIfAbsent".


      In addition, the example code should use HashSet::new according to lambda best practice.

      Not fixing this before JDK 8 will result in these methods receiving a lot less use than they should as developers will struggle to work out what they do.

      See core-libs-dev
      http://mail.openjdk.java.net/pipermail/core-libs-dev/2013-November/023556.html

        Attachments

          Activity

            People

            Assignee:
            Unassigned Unassigned
            Reporter:
            scolebourne Stephen Colebourne
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated: