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

Specify how positional arguments are separated

    XMLWordPrintable

Details

    • Bug
    • Resolution: Cannot Reproduce
    • P4
    • 20
    • 17, 18
    • tools

    Description

      Whitespace is used to separate arguments in JavaDoc tags. However, whether or not a particular occurrence of a whitespace character splits an argument into two arguments depends on the context. In the context of references, for example, whitespace inside parentheses does not separate arguments, whereas outside of parentheses it does. So this tag has the reference `Object#wait(long timeoutMillis, int nanos)`:

          {@link Object#wait(long timeoutMillis, int nanos)}
          
      Whereas this tag has a reference `Object#wait` and a label `(long timeoutMillis, int nanos)`:

          {@link Object#wait (long timeoutMillis, int nanos)}
          
      The problem might not be obvious when newlines (also whitespace) are at play. For example, if references are formatted to stay within a fixed line width:

          {@link Object#wait
          (long timeoutMillis, int nanos)}

      This needs to be specified in Documentation Comment Specification for the Standard Doclet.

      This came up with JDK-8250766, which in turn triggered JDK-8266567.

      Attachments

        Issue Links

          Activity

            People

              jjg Jonathan Gibbons
              prappo Pavel Rappo
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: