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

JShell: Fix the format of SourceCodeAnalysis#documentation

    XMLWordPrintable

Details

    • 9
    • b141
    • generic
    • generic
    • Verified

    Description

      Current format is:
      [FullTypeName DOT] Ident LPAREN [FullTypeName ParamName {COMMA FullTypeName ParamName} [COMMA FullTypeName ELLIPSIS ParamName]] RPAREN

      There are some problems:
      1. No return type
          Return type is one of the important things when we think about methods.

      2. No type parameters
          When the parameter types is the type parameter, the documentation is difficult to understand:

          java.util.Optional.of(T arg0) // what is T? what is the bound of T?

      3. No thrown type
      4. ParamName is useless
          Because it is always arg0, arg1, arg2, ..., argN.
      5. FullTypeName is too verbose.
          The class name is not simplified even if it is already imported.

      I propose the following format:
          Documentation = Constructor | Method
              Constructor = ConstructorName Arguments ThrowsOpt
                  ConstructorName = [TypeParameters] SimplifiedType
                  Arguments = LPAREN [SimplifiedType {COMMA SimplifiedType} [COMMA SimplifiedType ELLIPSIS]] RPAREN
                  ThworsOpt = [THROWS SimplifiedType {COMMA SimplifiedType}]
              Method = ReturnType MethodName Arguments ThrowsOpt
                  ReturnType = SimplifiedType
                  MethodName = [SimplifiedType DOT] [TypeParameters] Ident

      SimplifiedType is simplified by SnippetMaps#fullClassNameAndPackageToClass and with TypeParameter.

      Ex:
      void printf(String, Object...)

      void f(List<String>, Function<? super String,? extends String>)
      (when j.u.List, j.u.f.Function are imported)

      Attachments

        Issue Links

          Activity

            People

              shinyafox Shinya Yoshida
              shinyafox Shinya Yoshida
              Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: