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

JShell: Fix the format of SourceCodeAnalysis#documentation

XMLWordPrintable

    • 9
    • b141
    • generic
    • generic
    • Verified

      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)

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

              Created:
              Updated:
              Resolved: