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

JShell API: Provide kind() overrides and toString() comments

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Open
    • Priority: P4
    • Resolution: Unresolved
    • Affects Version/s: 9
    • Fix Version/s: tbd_major
    • Component/s: tools
    • Labels:

      Description

      * Please add useful, if vague, comments for toString overrides.

      * Provide overrides for methods to give method-specific information in subclasses; for example "kind()".

      I cannot see significant examples of the latter other than kind(), which on leaf classes document the return of a specific Kind.

      ---


      For the Snippet subclasses, many of them say something like:
      >
      > Snippet for a method definition. The Kind is Snippet.Kind.METHOD.

      The best place to say what Method.Snippet.kind() does is for javadoc for the Method.Snippet.kind() method :-)

      I strongly recommend creating overrides of the methods in the implementation expressly for the purposes of hosting the javadoc; e.g.

      /**
       * Returns Snippet.Kind.METHOD.
       * @return Snippet.Kind.METHOD
       */
      @Override
      public Snippet.Kind kind() {return super.kind();}

      The javax.lang.model API does this for its interfaces and classes.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              rfield Robert Field
              Reporter:
              rfield Robert Field
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated: